[dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation

DPDK patches and discussions
 help / color / mirror / Atom feed

* [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation
@ 2018-08-31 18:20 Luca Boccassi
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
                   ` (6 more replies)
  0 siblings, 7 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-08-31 18:20 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

I have tested this by using diffoscope between the docs built by the
makefiles and by this Meson patchset, and verified they are all
identical.

There are both a new "doc" target (ninja doc) and a configuration
option. This is due to the following bug in Meson:
https://github.com/mesonbuild/meson/issues/4107
because of it it's not possible to have simply an optional target,
as its files will not be installed.
So by default the documentation is off, if one wants to just build it
'ninja doc' can be used, but if one wants to both build and install
the config option 'enable_docs' has to be enabled.

A couple of small refactoring was done to the makefile doc build, to
make things easier and doable by both build systems.

Luca Boccassi (4):
  mk: use script to generate examples.dox
  mk: use templated doxygen config, modified on the fly
  build: use same version as make showversion in Meson
  build: generate API documentation with Meson

 doc/api/doxy-api.conf        | 87 --------------------------------
 doc/api/doxy-api.conf.in     | 96 ++++++++++++++++++++++++++++++++++++
 doc/api/generate_doxygen.sh  | 10 ++++
 doc/api/generate_examples.sh | 14 ++++++
 doc/api/meson.build          | 51 +++++++++++++++++++
 doc/build-sdk-meson.txt      |  2 +
 doc/meson.build              |  4 ++
 meson.build                  |  5 +-
 meson_options.txt            |  2 +
 mk/rte.sdkdoc.mk             | 21 +++-----
 10 files changed, 191 insertions(+), 101 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100755 doc/api/generate_examples.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
@ 2018-08-31 18:20 ` Luca Boccassi
  2018-09-03  0:54   ` Thomas Monjalon
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
                   ` (5 subsequent siblings)
  6 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-08-31 18:20 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will make it possible to generate the file in the same way from
Meson as well.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 doc/api/generate_examples.sh | 14 ++++++++++++++
 mk/rte.sdkdoc.mk             |  5 +----
 2 files changed, 15 insertions(+), 4 deletions(-)
 create mode 100755 doc/api/generate_examples.sh

diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
new file mode 100755
index 0000000000..9633a64f7a
--- /dev/null
+++ b/doc/api/generate_examples.sh
@@ -0,0 +1,14 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+EXAMPLES_DIR=$1
+API_EXAMPLES=$2
+
+# SC2129 - avoid multiple individual redirects
+{ \
+    printf '/**\n'; \
+    printf '@page examples DPDK Example Programs\n\n'; \
+    find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \
+    printf '*/\n'; \
+} > "${API_EXAMPLES}"
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index bd2e5763df..d023b720fe 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -63,10 +63,7 @@ api-html-clean:
 
 $(API_EXAMPLES): api-html-clean
 	$(Q)mkdir -p $(@D)
-	@printf '/**\n' > $(API_EXAMPLES)
-	@printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES)
-	@find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES)
-	@printf '*/\n' >> $(API_EXAMPLES)
+	$(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES)
 
 guides-pdf-clean: guides-pdf-img-clean
 guides-pdf-img-clean:
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-03  0:54   ` Thomas Monjalon
  2018-09-03  9:07     ` Luca Boccassi
  0 siblings, 1 reply; 39+ messages in thread
From: Thomas Monjalon @ 2018-09-03  0:54 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

31/08/2018 20:20, Luca Boccassi:
> +# SC2129 - avoid multiple individual redirects

What is SC2129 ?

> +{ \
> +    printf '/**\n'; \
> +    printf '@page examples DPDK Example Programs\n\n'; \
> +    find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort; \
> +    printf '*/\n'; \
> +} > "${API_EXAMPLES}"

Why using backslashes (continuation lines)?

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox
  2018-09-03  0:54   ` Thomas Monjalon
@ 2018-09-03  9:07     ` Luca Boccassi
  2018-09-07 16:13       ` Bruce Richardson
  0 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-09-03  9:07 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

On Mon, 2018-09-03 at 02:54 +0200, Thomas Monjalon wrote:
> 31/08/2018 20:20, Luca Boccassi:
> > +# SC2129 - avoid multiple individual redirects
> 
> What is SC2129 ?

shellcheck - will clarify in v2

> > +{ \
> > +    printf '/**\n'; \
> > +    printf '@page examples DPDK Example Programs\n\n'; \
> > +    find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example
> > examples/%P\n' | LC_ALL=C sort; \
> > +    printf '*/\n'; \
> > +} > "${API_EXAMPLES}"
> 
> Why using backslashes (continuation lines)?

Good point, will remove in v2

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox
  2018-09-03  9:07     ` Luca Boccassi
@ 2018-09-07 16:13       ` Bruce Richardson
  2018-09-07 16:56         ` Luca Boccassi
  0 siblings, 1 reply; 39+ messages in thread
From: Bruce Richardson @ 2018-09-07 16:13 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: Thomas Monjalon, dev, john.mcnamara, marko.kovacevic

On Mon, Sep 03, 2018 at 10:07:07AM +0100, Luca Boccassi wrote:
> On Mon, 2018-09-03 at 02:54 +0200, Thomas Monjalon wrote:
> > 31/08/2018 20:20, Luca Boccassi:
> > > +# SC2129 - avoid multiple individual redirects
> > 
> > What is SC2129 ?
> 
> shellcheck - will clarify in v2
> 
> > > +{ \
> > > +    printf '/**\n'; \
> > > +    printf '@page examples DPDK Example Programs\n\n'; \
> > > +    find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example
> > > examples/%P\n' | LC_ALL=C sort; \
> > > +    printf '*/\n'; \
> > > +} > "${API_EXAMPLES}"
> > 
> > Why using backslashes (continuation lines)?
> 
> Good point, will remove in v2
>
Agree, rather than using continuation lines, I suggest one of the
following:
* use exec > ${API_EXAMPLES} at the top of the script
* let the script just print to stdout and have make/meson put that in the
  output file for you.

/Bruce

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox
  2018-09-07 16:13       ` Bruce Richardson
@ 2018-09-07 16:56         ` Luca Boccassi
  0 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:56 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: Thomas Monjalon, dev, john.mcnamara, marko.kovacevic

On Fri, 2018-09-07 at 17:13 +0100, Bruce Richardson wrote:
> On Mon, Sep 03, 2018 at 10:07:07AM +0100, Luca Boccassi wrote:
> > On Mon, 2018-09-03 at 02:54 +0200, Thomas Monjalon wrote:
> > > 31/08/2018 20:20, Luca Boccassi:
> > > > +# SC2129 - avoid multiple individual redirects
> > > 
> > > What is SC2129 ?
> > 
> > shellcheck - will clarify in v2
> > 
> > > > +{ \
> > > > +    printf '/**\n'; \
> > > > +    printf '@page examples DPDK Example Programs\n\n'; \
> > > > +    find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@examp
> > > > le
> > > > examples/%P\n' | LC_ALL=C sort; \
> > > > +    printf '*/\n'; \
> > > > +} > "${API_EXAMPLES}"
> > > 
> > > Why using backslashes (continuation lines)?
> > 
> > Good point, will remove in v2
> > 
> 
> Agree, rather than using continuation lines, I suggest one of the
> following:
> * use exec > ${API_EXAMPLES} at the top of the script
> * let the script just print to stdout and have make/meson put that in
> the
>   output file for you.
> 
> /Bruce

exec > works and checkbashism is also happy with it, so used that in v2

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-08-31 18:20 ` Luca Boccassi
  2018-09-03  1:03   ` Thomas Monjalon
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson Luca Boccassi
                   ` (4 subsequent siblings)
  6 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-08-31 18:20 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will allow the same config file to be used from Meson.
The result has been verified to be identical via diffoscope.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 doc/api/doxy-api.conf    | 87 ------------------------------------
 doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++
 mk/rte.sdkdoc.mk         | 16 +++----
 3 files changed, 103 insertions(+), 96 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
deleted file mode 100644
index 66693c3835..0000000000
--- a/doc/api/doxy-api.conf
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013-2017 6WIND S.A.
-
-PROJECT_NAME            = DPDK
-INPUT                   = doc/api/doxy-api-index.md \
-                          drivers/crypto/scheduler \
-                          drivers/mempool/dpaa2 \
-                          drivers/net/bnxt \
-                          drivers/net/bonding \
-                          drivers/net/dpaa \
-                          drivers/net/i40e \
-                          drivers/net/ixgbe \
-                          drivers/net/softnic \
-                          drivers/raw/dpaa2_cmdif \
-                          drivers/raw/dpaa2_qdma \
-                          lib/librte_eal/common/include \
-                          lib/librte_eal/common/include/generic \
-                          lib/librte_acl \
-                          lib/librte_bbdev \
-                          lib/librte_bitratestats \
-                          lib/librte_bpf \
-                          lib/librte_cfgfile \
-                          lib/librte_cmdline \
-                          lib/librte_compat \
-                          lib/librte_compressdev \
-                          lib/librte_cryptodev \
-                          lib/librte_distributor \
-                          lib/librte_efd \
-                          lib/librte_ethdev \
-                          lib/librte_eventdev \
-                          lib/librte_flow_classify \
-                          lib/librte_gro \
-                          lib/librte_gso \
-                          lib/librte_hash \
-                          lib/librte_ip_frag \
-                          lib/librte_jobstats \
-                          lib/librte_kni \
-                          lib/librte_kvargs \
-                          lib/librte_latencystats \
-                          lib/librte_lpm \
-                          lib/librte_mbuf \
-                          lib/librte_member \
-                          lib/librte_mempool \
-                          lib/librte_meter \
-                          lib/librte_metrics \
-                          lib/librte_net \
-                          lib/librte_pci \
-                          lib/librte_pdump \
-                          lib/librte_pipeline \
-                          lib/librte_port \
-                          lib/librte_power \
-                          lib/librte_rawdev \
-                          lib/librte_reorder \
-                          lib/librte_ring \
-                          lib/librte_sched \
-                          lib/librte_security \
-                          lib/librte_table \
-                          lib/librte_timer \
-                          lib/librte_vhost
-FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
-PREDEFINED              = __DOXYGEN__ \
-			   VFIO_PRESENT \
-                          __attribute__(x)=
-
-OPTIMIZE_OUTPUT_FOR_C   = YES
-ENABLE_PREPROCESSING    = YES
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_STATIC          = YES
-DISTRIBUTE_GROUP_DOC    = YES
-HIDE_UNDOC_MEMBERS      = YES
-HIDE_UNDOC_CLASSES      = YES
-HIDE_SCOPE_NAMES        = YES
-GENERATE_DEPRECATEDLIST = NO
-VERBATIM_HEADERS        = NO
-ALPHABETICAL_INDEX      = NO
-
-HTML_TIMESTAMP          = NO
-HTML_DYNAMIC_SECTIONS   = YES
-SEARCHENGINE            = NO
-SORT_MEMBER_DOCS        = NO
-SOURCE_BROWSER          = YES
-
-EXAMPLE_PATH            = examples
-EXAMPLE_PATTERNS        = *.c
-EXAMPLE_RECURSIVE       = YES
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
new file mode 100644
index 0000000000..ccc1d4ab24
--- /dev/null
+++ b/doc/api/doxy-api.conf.in
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2013-2017 6WIND S.A.
+
+PROJECT_NAME            = DPDK
+INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/crypto/scheduler \
+                          @TOPDIR@/drivers/mempool/dpaa2 \
+                          @TOPDIR@/drivers/net/bnxt \
+                          @TOPDIR@/drivers/net/bonding \
+                          @TOPDIR@/drivers/net/dpaa \
+                          @TOPDIR@/drivers/net/i40e \
+                          @TOPDIR@/drivers/net/ixgbe \
+                          @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
+                          @TOPDIR@/drivers/raw/dpaa2_qdma \
+                          @TOPDIR@/lib/librte_eal/common/include \
+                          @TOPDIR@/lib/librte_eal/common/include/generic \
+                          @TOPDIR@/lib/librte_acl \
+                          @TOPDIR@/lib/librte_bbdev \
+                          @TOPDIR@/lib/librte_bitratestats \
+                          @TOPDIR@/lib/librte_bpf \
+                          @TOPDIR@/lib/librte_cfgfile \
+                          @TOPDIR@/lib/librte_cmdline \
+                          @TOPDIR@/lib/librte_compat \
+                          @TOPDIR@/lib/librte_compressdev \
+                          @TOPDIR@/lib/librte_cryptodev \
+                          @TOPDIR@/lib/librte_distributor \
+                          @TOPDIR@/lib/librte_efd \
+                          @TOPDIR@/lib/librte_ethdev \
+                          @TOPDIR@/lib/librte_eventdev \
+                          @TOPDIR@/lib/librte_flow_classify \
+                          @TOPDIR@/lib/librte_gro \
+                          @TOPDIR@/lib/librte_gso \
+                          @TOPDIR@/lib/librte_hash \
+                          @TOPDIR@/lib/librte_ip_frag \
+                          @TOPDIR@/lib/librte_jobstats \
+                          @TOPDIR@/lib/librte_kni \
+                          @TOPDIR@/lib/librte_kvargs \
+                          @TOPDIR@/lib/librte_latencystats \
+                          @TOPDIR@/lib/librte_lpm \
+                          @TOPDIR@/lib/librte_mbuf \
+                          @TOPDIR@/lib/librte_member \
+                          @TOPDIR@/lib/librte_mempool \
+                          @TOPDIR@/lib/librte_meter \
+                          @TOPDIR@/lib/librte_metrics \
+                          @TOPDIR@/lib/librte_net \
+                          @TOPDIR@/lib/librte_pci \
+                          @TOPDIR@/lib/librte_pdump \
+                          @TOPDIR@/lib/librte_pipeline \
+                          @TOPDIR@/lib/librte_port \
+                          @TOPDIR@/lib/librte_power \
+                          @TOPDIR@/lib/librte_rawdev \
+                          @TOPDIR@/lib/librte_reorder \
+                          @TOPDIR@/lib/librte_ring \
+                          @TOPDIR@/lib/librte_sched \
+                          @TOPDIR@/lib/librte_security \
+                          @TOPDIR@/lib/librte_table \
+                          @TOPDIR@/lib/librte_timer \
+                          @TOPDIR@/lib/librte_vhost
+FILE_PATTERNS           = rte_*.h \
+                          cmdline.h
+PREDEFINED              = __DOXYGEN__ \
+			   VFIO_PRESENT \
+                          __attribute__(x)=
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_STATIC          = YES
+DISTRIBUTE_GROUP_DOC    = YES
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_SCOPE_NAMES        = YES
+GENERATE_DEPRECATEDLIST = NO
+VERBATIM_HEADERS        = NO
+ALPHABETICAL_INDEX      = NO
+
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = YES
+SEARCHENGINE            = NO
+SORT_MEMBER_DOCS        = NO
+SOURCE_BROWSER          = YES
+
+EXAMPLE_PATH            = @TOPDIR@/examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
+
+PROJECT_NUMBER          = @VERSION@
+INPUT                   += @API_EXAMPLES@
+OUTPUT_DIRECTORY        = @OUTPUT@
+HTML_OUTPUT             = @HTML_OUTPUT@
+STRIP_FROM_PATH         = @STRIP_FROM_PATH@
+GENERATE_HTML           = YES
+GENERATE_LATEX          = NO
+GENERATE_MAN            = NO
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index d023b720fe..c44db6447a 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
 api-html: $(API_EXAMPLES)
 	@echo 'doxygen for API...'
 	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
-	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
-	    printf 'PROJECT_NUMBER = '                && \
-	                     $(MAKE) -rRs showversion && \
-	    echo INPUT           += $(API_EXAMPLES)   && \
-	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
-	    echo HTML_OUTPUT      = html/api          && \
-	    echo GENERATE_HTML    = YES               && \
-	    echo GENERATE_LATEX   = NO                && \
-	    echo GENERATE_MAN     = NO                )| \
+	$(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \
+	         -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|"       \
+	         -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|"           \
+	         -e "s|@HTML_OUTPUT@|html/api|"               \
+	         -e "s|@TOPDIR@|./|g"                         \
+	         -e "s|@STRIP_FROM_PATH@|./|g"                \
+	         $(RTE_SDK)/doc/api/doxy-api.conf.in)|        \
 	    doxygen -
 	$(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
 
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-09-03  1:03   ` Thomas Monjalon
  2018-09-03  9:08     ` Luca Boccassi
  0 siblings, 1 reply; 39+ messages in thread
From: Thomas Monjalon @ 2018-09-03  1:03 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

Good idea.
While at putting all in the same file (template),
we can re-organize the template a bit.

31/08/2018 20:20, Luca Boccassi:
> --- /dev/null
> +++ b/doc/api/doxy-api.conf.in
> @@ -0,0 +1,96 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright 2013-2017 6WIND S.A.
> +
> +PROJECT_NAME            = DPDK
> +INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
> +                          @TOPDIR@/drivers/crypto/scheduler \
> +                          @TOPDIR@/drivers/mempool/dpaa2 \
> +                          @TOPDIR@/drivers/net/bnxt \
> +                          @TOPDIR@/drivers/net/bonding \
> +                          @TOPDIR@/drivers/net/dpaa \
> +                          @TOPDIR@/drivers/net/i40e \
> +                          @TOPDIR@/drivers/net/ixgbe \
> +                          @TOPDIR@/drivers/net/softnic \
> +                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
> +                          @TOPDIR@/drivers/raw/dpaa2_qdma \
> +                          @TOPDIR@/lib/librte_eal/common/include \
> +                          @TOPDIR@/lib/librte_eal/common/include/generic \
> +                          @TOPDIR@/lib/librte_acl \
> +                          @TOPDIR@/lib/librte_bbdev \
> +                          @TOPDIR@/lib/librte_bitratestats \
> +                          @TOPDIR@/lib/librte_bpf \
> +                          @TOPDIR@/lib/librte_cfgfile \
> +                          @TOPDIR@/lib/librte_cmdline \
> +                          @TOPDIR@/lib/librte_compat \
> +                          @TOPDIR@/lib/librte_compressdev \
> +                          @TOPDIR@/lib/librte_cryptodev \
> +                          @TOPDIR@/lib/librte_distributor \
> +                          @TOPDIR@/lib/librte_efd \
> +                          @TOPDIR@/lib/librte_ethdev \
> +                          @TOPDIR@/lib/librte_eventdev \
> +                          @TOPDIR@/lib/librte_flow_classify \
> +                          @TOPDIR@/lib/librte_gro \
> +                          @TOPDIR@/lib/librte_gso \
> +                          @TOPDIR@/lib/librte_hash \
> +                          @TOPDIR@/lib/librte_ip_frag \
> +                          @TOPDIR@/lib/librte_jobstats \
> +                          @TOPDIR@/lib/librte_kni \
> +                          @TOPDIR@/lib/librte_kvargs \
> +                          @TOPDIR@/lib/librte_latencystats \
> +                          @TOPDIR@/lib/librte_lpm \
> +                          @TOPDIR@/lib/librte_mbuf \
> +                          @TOPDIR@/lib/librte_member \
> +                          @TOPDIR@/lib/librte_mempool \
> +                          @TOPDIR@/lib/librte_meter \
> +                          @TOPDIR@/lib/librte_metrics \
> +                          @TOPDIR@/lib/librte_net \
> +                          @TOPDIR@/lib/librte_pci \
> +                          @TOPDIR@/lib/librte_pdump \
> +                          @TOPDIR@/lib/librte_pipeline \
> +                          @TOPDIR@/lib/librte_port \
> +                          @TOPDIR@/lib/librte_power \
> +                          @TOPDIR@/lib/librte_rawdev \
> +                          @TOPDIR@/lib/librte_reorder \
> +                          @TOPDIR@/lib/librte_ring \
> +                          @TOPDIR@/lib/librte_sched \
> +                          @TOPDIR@/lib/librte_security \
> +                          @TOPDIR@/lib/librte_table \
> +                          @TOPDIR@/lib/librte_timer \
> +                          @TOPDIR@/lib/librte_vhost
> +FILE_PATTERNS           = rte_*.h \
> +                          cmdline.h
> +PREDEFINED              = __DOXYGEN__ \
> +			   VFIO_PRESENT \
> +                          __attribute__(x)=
> +
> +OPTIMIZE_OUTPUT_FOR_C   = YES
> +ENABLE_PREPROCESSING    = YES
> +MACRO_EXPANSION         = YES
> +EXPAND_ONLY_PREDEF      = YES
> +EXTRACT_STATIC          = YES
> +DISTRIBUTE_GROUP_DOC    = YES
> +HIDE_UNDOC_MEMBERS      = YES
> +HIDE_UNDOC_CLASSES      = YES
> +HIDE_SCOPE_NAMES        = YES
> +GENERATE_DEPRECATEDLIST = NO
> +VERBATIM_HEADERS        = NO
> +ALPHABETICAL_INDEX      = NO
> +
> +HTML_TIMESTAMP          = NO
> +HTML_DYNAMIC_SECTIONS   = YES
> +SEARCHENGINE            = NO
> +SORT_MEMBER_DOCS        = NO
> +SOURCE_BROWSER          = YES
> +
> +EXAMPLE_PATH            = @TOPDIR@/examples
> +EXAMPLE_PATTERNS        = *.c
> +EXAMPLE_RECURSIVE       = YES
> +
> +PROJECT_NUMBER          = @VERSION@

could be below PROJECT_NAME

> +INPUT                   += @API_EXAMPLES@

can be at the end of INPUT list

> +OUTPUT_DIRECTORY        = @OUTPUT@
> +HTML_OUTPUT             = @HTML_OUTPUT@

can be below GENERATE_HTML

> +STRIP_FROM_PATH         = @STRIP_FROM_PATH@
> +GENERATE_HTML           = YES
> +GENERATE_LATEX          = NO
> +GENERATE_MAN            = NO

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly
  2018-09-03  1:03   ` Thomas Monjalon
@ 2018-09-03  9:08     ` Luca Boccassi
  0 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-03  9:08 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

On Mon, 2018-09-03 at 03:03 +0200, Thomas Monjalon wrote:
> Good idea.
> While at putting all in the same file (template),
> we can re-organize the template a bit.
> 
> 31/08/2018 20:20, Luca Boccassi:
> > --- /dev/null
> > +++ b/doc/api/doxy-api.conf.in
> > @@ -0,0 +1,96 @@
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright 2013-2017 6WIND S.A.
> > +
> > +PROJECT_NAME            = DPDK
> > +INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
> > +                          @TOPDIR@/drivers/crypto/scheduler \
> > +                          @TOPDIR@/drivers/mempool/dpaa2 \
> > +                          @TOPDIR@/drivers/net/bnxt \
> > +                          @TOPDIR@/drivers/net/bonding \
> > +                          @TOPDIR@/drivers/net/dpaa \
> > +                          @TOPDIR@/drivers/net/i40e \
> > +                          @TOPDIR@/drivers/net/ixgbe \
> > +                          @TOPDIR@/drivers/net/softnic \
> > +                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
> > +                          @TOPDIR@/drivers/raw/dpaa2_qdma \
> > +                          @TOPDIR@/lib/librte_eal/common/include \
> > +                          @TOPDIR@/lib/librte_eal/common/include/g
> > eneric \
> > +                          @TOPDIR@/lib/librte_acl \
> > +                          @TOPDIR@/lib/librte_bbdev \
> > +                          @TOPDIR@/lib/librte_bitratestats \
> > +                          @TOPDIR@/lib/librte_bpf \
> > +                          @TOPDIR@/lib/librte_cfgfile \
> > +                          @TOPDIR@/lib/librte_cmdline \
> > +                          @TOPDIR@/lib/librte_compat \
> > +                          @TOPDIR@/lib/librte_compressdev \
> > +                          @TOPDIR@/lib/librte_cryptodev \
> > +                          @TOPDIR@/lib/librte_distributor \
> > +                          @TOPDIR@/lib/librte_efd \
> > +                          @TOPDIR@/lib/librte_ethdev \
> > +                          @TOPDIR@/lib/librte_eventdev \
> > +                          @TOPDIR@/lib/librte_flow_classify \
> > +                          @TOPDIR@/lib/librte_gro \
> > +                          @TOPDIR@/lib/librte_gso \
> > +                          @TOPDIR@/lib/librte_hash \
> > +                          @TOPDIR@/lib/librte_ip_frag \
> > +                          @TOPDIR@/lib/librte_jobstats \
> > +                          @TOPDIR@/lib/librte_kni \
> > +                          @TOPDIR@/lib/librte_kvargs \
> > +                          @TOPDIR@/lib/librte_latencystats \
> > +                          @TOPDIR@/lib/librte_lpm \
> > +                          @TOPDIR@/lib/librte_mbuf \
> > +                          @TOPDIR@/lib/librte_member \
> > +                          @TOPDIR@/lib/librte_mempool \
> > +                          @TOPDIR@/lib/librte_meter \
> > +                          @TOPDIR@/lib/librte_metrics \
> > +                          @TOPDIR@/lib/librte_net \
> > +                          @TOPDIR@/lib/librte_pci \
> > +                          @TOPDIR@/lib/librte_pdump \
> > +                          @TOPDIR@/lib/librte_pipeline \
> > +                          @TOPDIR@/lib/librte_port \
> > +                          @TOPDIR@/lib/librte_power \
> > +                          @TOPDIR@/lib/librte_rawdev \
> > +                          @TOPDIR@/lib/librte_reorder \
> > +                          @TOPDIR@/lib/librte_ring \
> > +                          @TOPDIR@/lib/librte_sched \
> > +                          @TOPDIR@/lib/librte_security \
> > +                          @TOPDIR@/lib/librte_table \
> > +                          @TOPDIR@/lib/librte_timer \
> > +                          @TOPDIR@/lib/librte_vhost
> > +FILE_PATTERNS           = rte_*.h \
> > +                          cmdline.h
> > +PREDEFINED              = __DOXYGEN__ \
> > +			   VFIO_PRESENT \
> > +                          __attribute__(x)=
> > +
> > +OPTIMIZE_OUTPUT_FOR_C   = YES
> > +ENABLE_PREPROCESSING    = YES
> > +MACRO_EXPANSION         = YES
> > +EXPAND_ONLY_PREDEF      = YES
> > +EXTRACT_STATIC          = YES
> > +DISTRIBUTE_GROUP_DOC    = YES
> > +HIDE_UNDOC_MEMBERS      = YES
> > +HIDE_UNDOC_CLASSES      = YES
> > +HIDE_SCOPE_NAMES        = YES
> > +GENERATE_DEPRECATEDLIST = NO
> > +VERBATIM_HEADERS        = NO
> > +ALPHABETICAL_INDEX      = NO
> > +
> > +HTML_TIMESTAMP          = NO
> > +HTML_DYNAMIC_SECTIONS   = YES
> > +SEARCHENGINE            = NO
> > +SORT_MEMBER_DOCS        = NO
> > +SOURCE_BROWSER          = YES
> > +
> > +EXAMPLE_PATH            = @TOPDIR@/examples
> > +EXAMPLE_PATTERNS        = *.c
> > +EXAMPLE_RECURSIVE       = YES
> > +
> > +PROJECT_NUMBER          = @VERSION@
> 
> could be below PROJECT_NAME
> 
> > +INPUT                   += @API_EXAMPLES@
> 
> can be at the end of INPUT list
> 
> > +OUTPUT_DIRECTORY        = @OUTPUT@
> > +HTML_OUTPUT             = @HTML_OUTPUT@
> 
> can be below GENERATE_HTML
> 
> > +STRIP_FROM_PATH         = @STRIP_FROM_PATH@
> > +GENERATE_HTML           = YES
> > +GENERATE_LATEX          = NO
> > +GENERATE_MAN            = NO

Ok, will do in v2

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-08-31 18:20 ` Luca Boccassi
  2018-09-03  1:04   ` Thomas Monjalon
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
                   ` (3 subsequent siblings)
  6 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-08-31 18:20 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
causing among other things a difference in the generated documentation.

Fixes: 76b9d9de5c7d ("version: 18.11-rc0")

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index 84af32ecef..9999e8640a 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # Copyright(c) 2017 Intel Corporation
 
 project('DPDK', 'C',
-	version: '18.11-rc0',
+	version: '18.11.0-rc0',
 	license: 'BSD',
 	default_options: ['buildtype=release', 'default_library=static'],
 	meson_version: '>= 0.41'
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-09-03  1:04   ` Thomas Monjalon
  0 siblings, 0 replies; 39+ messages in thread
From: Thomas Monjalon @ 2018-09-03  1:04 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

31/08/2018 20:20, Luca Boccassi:
> make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
> causing among other things a difference in the generated documentation.
> 
> Fixes: 76b9d9de5c7d ("version: 18.11-rc0")
> 
> Signed-off-by: Luca Boccassi <bluca@debian.org>

Acked-by: Thomas Monjalon <thomas@monjalon.net>

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
                   ` (2 preceding siblings ...)
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-08-31 18:20 ` Luca Boccassi
  2018-09-03  1:09   ` Thomas Monjalon
  2018-09-07 16:31   ` Bruce Richardson
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
                   ` (2 subsequent siblings)
  6 siblings, 2 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-08-31 18:20 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

Both a configuration-time "enable_docs" boolean option and an optional
'ninja doc' target are available. Note that due to a Meson bug for now
the latter will only build, but not install the files.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 doc/api/generate_doxygen.sh | 10 ++++++++
 doc/api/meson.build         | 51 +++++++++++++++++++++++++++++++++++++
 doc/build-sdk-meson.txt     |  2 ++
 doc/meson.build             |  4 +++
 meson.build                 |  3 +++
 meson_options.txt           |  2 ++
 6 files changed, 72 insertions(+)
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..e44963e4a9
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+# due to the CSS customisation script, which needs to run on a file that
+# is in a subdirectory that is created at build time and thus it cannot
+# be an individual custom_target, we need to wrap the doxygen call in a
+# script to run the CSS modification afterwards
+generate_doxygen = find_program('generate_doxygen.sh')
+generate_examples = find_program('generate_examples.sh')
+generate_css = find_program('doxy-html-custom.sh')
+doxygen = find_program('doxygen')
+
+inputdir = join_paths(meson.source_root(), 'examples')
+htmldir = join_paths('doc', 'html')
+
+# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+# if install is set to true it will override build_by_default and it will
+# cause the target to always be built. If install were to be always set to
+# false it would be impossible to install the docs.
+# So use a configure option for now.
+example = custom_target('examples.dox',
+	input: inputdir,
+	output: 'examples.dox',
+	command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+	install: get_option('enable_docs'),
+	install_dir: htmldir,
+	build_by_default: false)
+
+cdata = configuration_data()
+cdata.set('VERSION', meson.project_version())
+cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
+cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
+cdata.set('HTML_OUTPUT', 'api')
+cdata.set('TOPDIR', meson.source_root())
+cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+doxy_conf = configure_file(input: 'doxy-api.conf.in',
+	output: 'doxy-api.conf',
+	configuration: cdata,
+	install: false)
+
+doxy_build = custom_target('doxygen',
+	depends: example,
+	input: doxy_conf,
+	output: 'api',
+	command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+	install: get_option('enable_docs'),
+	install_dir: htmldir,
+	build_by_default: false)
+
+run_target('doc', command: 'true', depends: doxy_build)
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
 
 	meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
 
+	meson -Denable_docs=true fullbuild  # build and install docs
+
 Examples of setting the same options using meson configure::
 
 	meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
 subdir('app')
 subdir('test')
 
+# build docs
+subdir('doc')
+
 # build any examples explicitly requested - useful for developers
 if get_option('examples') != ''
 	subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
 	description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
 option('enable_kmods', type: 'boolean', value: true,
 	description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+	description: 'build documentation')
 option('examples', type: 'string', value: '',
 	description: 'Comma-separated list of examples to build by default')
 option('include_subdir_arch', type: 'string', value: '',
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-03  1:09   ` Thomas Monjalon
  2018-09-03  9:34     ` Luca Boccassi
  2018-09-07 16:31   ` Bruce Richardson
  1 sibling, 1 reply; 39+ messages in thread
From: Thomas Monjalon @ 2018-09-03  1:09 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

31/08/2018 20:20, Luca Boccassi:
> Both a configuration-time "enable_docs" boolean option and an optional
> 'ninja doc' target are available. Note that due to a Meson bug for now
> the latter will only build, but not install the files.
> 
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> ---
>  doc/api/generate_doxygen.sh | 10 ++++++++
>  doc/api/meson.build         | 51 +++++++++++++++++++++++++++++++++++++
>  doc/build-sdk-meson.txt     |  2 ++
>  doc/meson.build             |  4 +++
>  meson.build                 |  3 +++
>  meson_options.txt           |  2 ++
>  6 files changed, 72 insertions(+)

You use generate_doxygen.sh only with meson?
Shouldn't we use the same in mk/rte.sdkdoc.mk?

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson
  2018-09-03  1:09   ` Thomas Monjalon
@ 2018-09-03  9:34     ` Luca Boccassi
  0 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-03  9:34 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

On Mon, 2018-09-03 at 03:09 +0200, Thomas Monjalon wrote:
> 31/08/2018 20:20, Luca Boccassi:
> > Both a configuration-time "enable_docs" boolean option and an
> > optional
> > 'ninja doc' target are available. Note that due to a Meson bug for
> > now
> > the latter will only build, but not install the files.
> > 
> > Signed-off-by: Luca Boccassi <bluca@debian.org>
> > ---
> >  doc/api/generate_doxygen.sh | 10 ++++++++
> >  doc/api/meson.build         | 51
> > +++++++++++++++++++++++++++++++++++++
> >  doc/build-sdk-meson.txt     |  2 ++
> >  doc/meson.build             |  4 +++
> >  meson.build                 |  3 +++
> >  meson_options.txt           |  2 ++
> >  6 files changed, 72 insertions(+)
> 
> You use generate_doxygen.sh only with meson?
> Shouldn't we use the same in mk/rte.sdkdoc.mk?

I was kinda hoping somebody would be able to suggest an alternative
that avoids the need for generate_doxygen.sh - the issue being that
with Meson's "custom_target" you can't specify a subdirectory in
input/ouput (and the directory is generated at build time so can't have
a meson.build in it), and also you cannot use the same "output" twice.

So I can't see a way to have an additional custom_target to run the CSS
generation, hence the script.

Changing the makefile to use the script will make it a bit more
complicated, as the doxygen file will need to be generated rather than
passed by piping stout/in, so the rule will have to be split into 3:
create directory -> create file -> call doxygen. Not sure it's worth
it?

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
  2018-09-03  1:09   ` Thomas Monjalon
@ 2018-09-07 16:31   ` Bruce Richardson
  2018-09-07 16:56     ` Luca Boccassi
  1 sibling, 1 reply; 39+ messages in thread
From: Bruce Richardson @ 2018-09-07 16:31 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Fri, Aug 31, 2018 at 07:20:55PM +0100, Luca Boccassi wrote:
> Both a configuration-time "enable_docs" boolean option and an optional
> 'ninja doc' target are available. Note that due to a Meson bug for now
> the latter will only build, but not install the files.
> 
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> ---
>  doc/api/generate_doxygen.sh | 10 ++++++++
>  doc/api/meson.build         | 51 +++++++++++++++++++++++++++++++++++++
>  doc/build-sdk-meson.txt     |  2 ++
>  doc/meson.build             |  4 +++
>  meson.build                 |  3 +++
>  meson_options.txt           |  2 ++
>  6 files changed, 72 insertions(+)
>  create mode 100755 doc/api/generate_doxygen.sh
>  create mode 100644 doc/api/meson.build
>  create mode 100644 doc/meson.build
> 
> diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
> new file mode 100755
> index 0000000000..ab57660958
> --- /dev/null
> +++ b/doc/api/generate_doxygen.sh
> @@ -0,0 +1,10 @@
> +#! /bin/sh -e
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> +
> +DOXYCONF=$1
> +OUTDIR=$2
> +SCRIPTCSS=$3
> +
> +doxygen "${DOXYCONF}"
> +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> diff --git a/doc/api/meson.build b/doc/api/meson.build
> new file mode 100644
> index 0000000000..e44963e4a9
> --- /dev/null
> +++ b/doc/api/meson.build
> @@ -0,0 +1,51 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> +
> +# due to the CSS customisation script, which needs to run on a file that
> +# is in a subdirectory that is created at build time and thus it cannot
> +# be an individual custom_target, we need to wrap the doxygen call in a
> +# script to run the CSS modification afterwards
> +generate_doxygen = find_program('generate_doxygen.sh')
> +generate_examples = find_program('generate_examples.sh')
> +generate_css = find_program('doxy-html-custom.sh')
> +doxygen = find_program('doxygen')

This needs to be inside a conditional if we are not building docs.
Otherwise overall build will error out if doxygen is missing - even if
unused.

/Bruce

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson
  2018-09-07 16:31   ` Bruce Richardson
@ 2018-09-07 16:56     ` Luca Boccassi
  0 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:56 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Fri, 2018-09-07 at 17:31 +0100, Bruce Richardson wrote:
> On Fri, Aug 31, 2018 at 07:20:55PM +0100, Luca Boccassi wrote:
> > Both a configuration-time "enable_docs" boolean option and an
> > optional
> > 'ninja doc' target are available. Note that due to a Meson bug for
> > now
> > the latter will only build, but not install the files.
> > 
> > Signed-off-by: Luca Boccassi <bluca@debian.org>
> > ---
> >  doc/api/generate_doxygen.sh | 10 ++++++++
> >  doc/api/meson.build         | 51
> > +++++++++++++++++++++++++++++++++++++
> >  doc/build-sdk-meson.txt     |  2 ++
> >  doc/meson.build             |  4 +++
> >  meson.build                 |  3 +++
> >  meson_options.txt           |  2 ++
> >  6 files changed, 72 insertions(+)
> >  create mode 100755 doc/api/generate_doxygen.sh
> >  create mode 100644 doc/api/meson.build
> >  create mode 100644 doc/meson.build
> > 
> > diff --git a/doc/api/generate_doxygen.sh
> > b/doc/api/generate_doxygen.sh
> > new file mode 100755
> > index 0000000000..ab57660958
> > --- /dev/null
> > +++ b/doc/api/generate_doxygen.sh
> > @@ -0,0 +1,10 @@
> > +#! /bin/sh -e
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +DOXYCONF=$1
> > +OUTDIR=$2
> > +SCRIPTCSS=$3
> > +
> > +doxygen "${DOXYCONF}"
> > +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> > diff --git a/doc/api/meson.build b/doc/api/meson.build
> > new file mode 100644
> > index 0000000000..e44963e4a9
> > --- /dev/null
> > +++ b/doc/api/meson.build
> > @@ -0,0 +1,51 @@
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +# due to the CSS customisation script, which needs to run on a
> > file that
> > +# is in a subdirectory that is created at build time and thus it
> > cannot
> > +# be an individual custom_target, we need to wrap the doxygen call
> > in a
> > +# script to run the CSS modification afterwards
> > +generate_doxygen = find_program('generate_doxygen.sh')
> > +generate_examples = find_program('generate_examples.sh')
> > +generate_css = find_program('doxy-html-custom.sh')
> > +doxygen = find_program('doxygen')
> 
> This needs to be inside a conditional if we are not building docs.
> Otherwise overall build will error out if doxygen is missing - even
> if
> unused.
> 
> /Bruce

Good point, forgot about that, done in v2

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
                   ` (3 preceding siblings ...)
  2018-08-31 18:20 ` [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-07 16:55 ` Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
                     ` (4 more replies)
  2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
  6 siblings, 5 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:55 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will make it possible to generate the file in the same way from
Meson as well.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: simplified script by using exec > file

 doc/api/generate_examples.sh | 12 ++++++++++++
 mk/rte.sdkdoc.mk             |  5 +----
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100755 doc/api/generate_examples.sh

diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
new file mode 100755
index 0000000000..6fcfe513b6
--- /dev/null
+++ b/doc/api/generate_examples.sh
@@ -0,0 +1,12 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+EXAMPLES_DIR=$1
+API_EXAMPLES=$2
+
+exec > "${API_EXAMPLES}"
+printf '/**\n'
+printf '@page examples DPDK Example Programs\n\n'
+find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort
+printf '*/\n'
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index bd2e5763df..d023b720fe 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -63,10 +63,7 @@ api-html-clean:
 
 $(API_EXAMPLES): api-html-clean
 	$(Q)mkdir -p $(@D)
-	@printf '/**\n' > $(API_EXAMPLES)
-	@printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES)
-	@find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES)
-	@printf '*/\n' >> $(API_EXAMPLES)
+	$(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES)
 
 guides-pdf-clean: guides-pdf-img-clean
 guides-pdf-img-clean:
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-07 16:55   ` Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 3/4] build: use same version as make showversion in Meson Luca Boccassi
                     ` (3 subsequent siblings)
  4 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:55 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will allow the same config file to be used from Meson.
The result has been verified to be identical via diffoscope.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: reordered generated fields as requested

 doc/api/doxy-api.conf    | 87 ------------------------------------
 doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++
 mk/rte.sdkdoc.mk         | 16 +++----
 3 files changed, 103 insertions(+), 96 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
deleted file mode 100644
index 66693c3835..0000000000
--- a/doc/api/doxy-api.conf
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013-2017 6WIND S.A.
-
-PROJECT_NAME            = DPDK
-INPUT                   = doc/api/doxy-api-index.md \
-                          drivers/crypto/scheduler \
-                          drivers/mempool/dpaa2 \
-                          drivers/net/bnxt \
-                          drivers/net/bonding \
-                          drivers/net/dpaa \
-                          drivers/net/i40e \
-                          drivers/net/ixgbe \
-                          drivers/net/softnic \
-                          drivers/raw/dpaa2_cmdif \
-                          drivers/raw/dpaa2_qdma \
-                          lib/librte_eal/common/include \
-                          lib/librte_eal/common/include/generic \
-                          lib/librte_acl \
-                          lib/librte_bbdev \
-                          lib/librte_bitratestats \
-                          lib/librte_bpf \
-                          lib/librte_cfgfile \
-                          lib/librte_cmdline \
-                          lib/librte_compat \
-                          lib/librte_compressdev \
-                          lib/librte_cryptodev \
-                          lib/librte_distributor \
-                          lib/librte_efd \
-                          lib/librte_ethdev \
-                          lib/librte_eventdev \
-                          lib/librte_flow_classify \
-                          lib/librte_gro \
-                          lib/librte_gso \
-                          lib/librte_hash \
-                          lib/librte_ip_frag \
-                          lib/librte_jobstats \
-                          lib/librte_kni \
-                          lib/librte_kvargs \
-                          lib/librte_latencystats \
-                          lib/librte_lpm \
-                          lib/librte_mbuf \
-                          lib/librte_member \
-                          lib/librte_mempool \
-                          lib/librte_meter \
-                          lib/librte_metrics \
-                          lib/librte_net \
-                          lib/librte_pci \
-                          lib/librte_pdump \
-                          lib/librte_pipeline \
-                          lib/librte_port \
-                          lib/librte_power \
-                          lib/librte_rawdev \
-                          lib/librte_reorder \
-                          lib/librte_ring \
-                          lib/librte_sched \
-                          lib/librte_security \
-                          lib/librte_table \
-                          lib/librte_timer \
-                          lib/librte_vhost
-FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
-PREDEFINED              = __DOXYGEN__ \
-			   VFIO_PRESENT \
-                          __attribute__(x)=
-
-OPTIMIZE_OUTPUT_FOR_C   = YES
-ENABLE_PREPROCESSING    = YES
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_STATIC          = YES
-DISTRIBUTE_GROUP_DOC    = YES
-HIDE_UNDOC_MEMBERS      = YES
-HIDE_UNDOC_CLASSES      = YES
-HIDE_SCOPE_NAMES        = YES
-GENERATE_DEPRECATEDLIST = NO
-VERBATIM_HEADERS        = NO
-ALPHABETICAL_INDEX      = NO
-
-HTML_TIMESTAMP          = NO
-HTML_DYNAMIC_SECTIONS   = YES
-SEARCHENGINE            = NO
-SORT_MEMBER_DOCS        = NO
-SOURCE_BROWSER          = YES
-
-EXAMPLE_PATH            = examples
-EXAMPLE_PATTERNS        = *.c
-EXAMPLE_RECURSIVE       = YES
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
new file mode 100644
index 0000000000..c3d8fdef18
--- /dev/null
+++ b/doc/api/doxy-api.conf.in
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2013-2017 6WIND S.A.
+
+PROJECT_NAME            = DPDK
+PROJECT_NUMBER          = @VERSION@
+INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/crypto/scheduler \
+                          @TOPDIR@/drivers/mempool/dpaa2 \
+                          @TOPDIR@/drivers/net/bnxt \
+                          @TOPDIR@/drivers/net/bonding \
+                          @TOPDIR@/drivers/net/dpaa \
+                          @TOPDIR@/drivers/net/i40e \
+                          @TOPDIR@/drivers/net/ixgbe \
+                          @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
+                          @TOPDIR@/drivers/raw/dpaa2_qdma \
+                          @TOPDIR@/lib/librte_eal/common/include \
+                          @TOPDIR@/lib/librte_eal/common/include/generic \
+                          @TOPDIR@/lib/librte_acl \
+                          @TOPDIR@/lib/librte_bbdev \
+                          @TOPDIR@/lib/librte_bitratestats \
+                          @TOPDIR@/lib/librte_bpf \
+                          @TOPDIR@/lib/librte_cfgfile \
+                          @TOPDIR@/lib/librte_cmdline \
+                          @TOPDIR@/lib/librte_compat \
+                          @TOPDIR@/lib/librte_compressdev \
+                          @TOPDIR@/lib/librte_cryptodev \
+                          @TOPDIR@/lib/librte_distributor \
+                          @TOPDIR@/lib/librte_efd \
+                          @TOPDIR@/lib/librte_ethdev \
+                          @TOPDIR@/lib/librte_eventdev \
+                          @TOPDIR@/lib/librte_flow_classify \
+                          @TOPDIR@/lib/librte_gro \
+                          @TOPDIR@/lib/librte_gso \
+                          @TOPDIR@/lib/librte_hash \
+                          @TOPDIR@/lib/librte_ip_frag \
+                          @TOPDIR@/lib/librte_jobstats \
+                          @TOPDIR@/lib/librte_kni \
+                          @TOPDIR@/lib/librte_kvargs \
+                          @TOPDIR@/lib/librte_latencystats \
+                          @TOPDIR@/lib/librte_lpm \
+                          @TOPDIR@/lib/librte_mbuf \
+                          @TOPDIR@/lib/librte_member \
+                          @TOPDIR@/lib/librte_mempool \
+                          @TOPDIR@/lib/librte_meter \
+                          @TOPDIR@/lib/librte_metrics \
+                          @TOPDIR@/lib/librte_net \
+                          @TOPDIR@/lib/librte_pci \
+                          @TOPDIR@/lib/librte_pdump \
+                          @TOPDIR@/lib/librte_pipeline \
+                          @TOPDIR@/lib/librte_port \
+                          @TOPDIR@/lib/librte_power \
+                          @TOPDIR@/lib/librte_rawdev \
+                          @TOPDIR@/lib/librte_reorder \
+                          @TOPDIR@/lib/librte_ring \
+                          @TOPDIR@/lib/librte_sched \
+                          @TOPDIR@/lib/librte_security \
+                          @TOPDIR@/lib/librte_table \
+                          @TOPDIR@/lib/librte_timer \
+                          @TOPDIR@/lib/librte_vhost
+INPUT                   += @API_EXAMPLES@
+FILE_PATTERNS           = rte_*.h \
+                          cmdline.h
+PREDEFINED              = __DOXYGEN__ \
+			   VFIO_PRESENT \
+                          __attribute__(x)=
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_STATIC          = YES
+DISTRIBUTE_GROUP_DOC    = YES
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_SCOPE_NAMES        = YES
+GENERATE_DEPRECATEDLIST = NO
+VERBATIM_HEADERS        = NO
+ALPHABETICAL_INDEX      = NO
+
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = YES
+SEARCHENGINE            = NO
+SORT_MEMBER_DOCS        = NO
+SOURCE_BROWSER          = YES
+
+EXAMPLE_PATH            = @TOPDIR@/examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
+
+OUTPUT_DIRECTORY        = @OUTPUT@
+STRIP_FROM_PATH         = @STRIP_FROM_PATH@
+GENERATE_HTML           = YES
+HTML_OUTPUT             = @HTML_OUTPUT@
+GENERATE_LATEX          = NO
+GENERATE_MAN            = NO
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index d023b720fe..c44db6447a 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
 api-html: $(API_EXAMPLES)
 	@echo 'doxygen for API...'
 	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
-	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
-	    printf 'PROJECT_NUMBER = '                && \
-	                     $(MAKE) -rRs showversion && \
-	    echo INPUT           += $(API_EXAMPLES)   && \
-	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
-	    echo HTML_OUTPUT      = html/api          && \
-	    echo GENERATE_HTML    = YES               && \
-	    echo GENERATE_LATEX   = NO                && \
-	    echo GENERATE_MAN     = NO                )| \
+	$(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \
+	         -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|"       \
+	         -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|"           \
+	         -e "s|@HTML_OUTPUT@|html/api|"               \
+	         -e "s|@TOPDIR@|./|g"                         \
+	         -e "s|@STRIP_FROM_PATH@|./|g"                \
+	         $(RTE_SDK)/doc/api/doxy-api.conf.in)|        \
 	    doxygen -
 	$(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
 
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v2 3/4] build: use same version as make showversion in Meson
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-09-07 16:55   ` Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson Luca Boccassi
                     ` (2 subsequent siblings)
  4 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:55 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
causing among other things a difference in the generated documentation.

Fixes: 76b9d9de5c7d ("version: 18.11-rc0")

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index 84af32ecef..9999e8640a 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # Copyright(c) 2017 Intel Corporation
 
 project('DPDK', 'C',
-	version: '18.11-rc0',
+	version: '18.11.0-rc0',
 	license: 'BSD',
 	default_options: ['buildtype=release', 'default_library=static'],
 	meson_version: '>= 0.41'
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-09-07 16:55   ` Luca Boccassi
  2018-09-10 15:47     ` Bruce Richardson
  2018-09-10 15:49   ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Bruce Richardson
  2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
  4 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-09-07 16:55 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: made doxygen dependency optional, skip doxygen build when not found

 doc/api/generate_doxygen.sh | 10 +++++++
 doc/api/meson.build         | 54 +++++++++++++++++++++++++++++++++++++
 doc/build-sdk-meson.txt     |  2 ++
 doc/meson.build             |  4 +++
 meson.build                 |  3 +++
 meson_options.txt           |  2 ++
 6 files changed, 75 insertions(+)
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..5dfa0fe044
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+doxygen = find_program('doxygen', required: false)
+
+if doxygen.found()
+	# due to the CSS customisation script, which needs to run on a file that
+	# is in a subdirectory that is created at build time and thus it cannot
+	# be an individual custom_target, we need to wrap the doxygen call in a
+	# script to run the CSS modification afterwards
+	generate_doxygen = find_program('generate_doxygen.sh')
+	generate_examples = find_program('generate_examples.sh')
+	generate_css = find_program('doxy-html-custom.sh')
+
+	inputdir = join_paths(meson.source_root(), 'examples')
+	htmldir = join_paths('doc', 'html')
+
+	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+	# if install is set to true it will override build_by_default and it will
+	# cause the target to always be built. If install were to be always set to
+	# false it would be impossible to install the docs.
+	# So use a configure option for now.
+	example = custom_target('examples.dox',
+		input: inputdir,
+		output: 'examples.dox',
+		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	cdata = configuration_data()
+	cdata.set('VERSION', meson.project_version())
+	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
+	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
+	cdata.set('HTML_OUTPUT', 'api')
+	cdata.set('TOPDIR', meson.source_root())
+	cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+	doxy_conf = configure_file(input: 'doxy-api.conf.in',
+		output: 'doxy-api.conf',
+		configuration: cdata,
+		install: false)
+
+	doxy_build = custom_target('doxygen',
+		depends: example,
+		input: doxy_conf,
+		output: 'api',
+		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	run_target('doc', command: 'true', depends: doxy_build)
+endif
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
 
 	meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
 
+	meson -Denable_docs=true fullbuild  # build and install docs
+
 Examples of setting the same options using meson configure::
 
 	meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
 subdir('app')
 subdir('test')
 
+# build docs
+subdir('doc')
+
 # build any examples explicitly requested - useful for developers
 if get_option('examples') != ''
 	subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
 	description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
 option('enable_kmods', type: 'boolean', value: true,
 	description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+	description: 'build documentation')
 option('examples', type: 'string', value: '',
 	description: 'Comma-separated list of examples to build by default')
 option('include_subdir_arch', type: 'string', value: '',
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-10 15:47     ` Bruce Richardson
  2018-09-10 16:15       ` Luca Boccassi
  0 siblings, 1 reply; 39+ messages in thread
From: Bruce Richardson @ 2018-09-10 15:47 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Fri, Sep 07, 2018 at 05:55:24PM +0100, Luca Boccassi wrote:
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> ---
> v2: made doxygen dependency optional, skip doxygen build when not found
> 
>  doc/api/generate_doxygen.sh | 10 +++++++
>  doc/api/meson.build         | 54 +++++++++++++++++++++++++++++++++++++
>  doc/build-sdk-meson.txt     |  2 ++
>  doc/meson.build             |  4 +++
>  meson.build                 |  3 +++
>  meson_options.txt           |  2 ++
>  6 files changed, 75 insertions(+)
>  create mode 100755 doc/api/generate_doxygen.sh
>  create mode 100644 doc/api/meson.build
>  create mode 100644 doc/meson.build
> 
> diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
> new file mode 100755
> index 0000000000..ab57660958
> --- /dev/null
> +++ b/doc/api/generate_doxygen.sh
> @@ -0,0 +1,10 @@
> +#! /bin/sh -e
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> +
> +DOXYCONF=$1
> +OUTDIR=$2
> +SCRIPTCSS=$3
> +
> +doxygen "${DOXYCONF}"
> +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> diff --git a/doc/api/meson.build b/doc/api/meson.build
> new file mode 100644
> index 0000000000..5dfa0fe044
> --- /dev/null
> +++ b/doc/api/meson.build
> @@ -0,0 +1,54 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> +
> +doxygen = find_program('doxygen', required: false)

Thinking about it, I think that "required" should be set to
"get_option(enable_docs)", since if someone explicitly enables the docs
they should be built and cause error if they can't be.

> +
> +if doxygen.found()
> +	# due to the CSS customisation script, which needs to run on a file that
> +	# is in a subdirectory that is created at build time and thus it cannot
> +	# be an individual custom_target, we need to wrap the doxygen call in a
> +	# script to run the CSS modification afterwards
> +	generate_doxygen = find_program('generate_doxygen.sh')
> +	generate_examples = find_program('generate_examples.sh')
> +	generate_css = find_program('doxy-html-custom.sh')
> +
> +	inputdir = join_paths(meson.source_root(), 'examples')
> +	htmldir = join_paths('doc', 'html')
> +
> +	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
> +	# if install is set to true it will override build_by_default and it will
> +	# cause the target to always be built. If install were to be always set to
> +	# false it would be impossible to install the docs.
> +	# So use a configure option for now.
> +	example = custom_target('examples.dox',
> +		input: inputdir,
> +		output: 'examples.dox',
> +		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
> +		install: get_option('enable_docs'),
> +		install_dir: htmldir,
> +		build_by_default: false)
> +
> +	cdata = configuration_data()
> +	cdata.set('VERSION', meson.project_version())
> +	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
> +	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
> +	cdata.set('HTML_OUTPUT', 'api')
> +	cdata.set('TOPDIR', meson.source_root())
> +	cdata.set('STRIP_FROM_PATH', meson.source_root())
> +
> +	doxy_conf = configure_file(input: 'doxy-api.conf.in',
> +		output: 'doxy-api.conf',
> +		configuration: cdata,
> +		install: false)
> +
> +	doxy_build = custom_target('doxygen',
> +		depends: example,
> +		input: doxy_conf,
> +		output: 'api',
> +		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
> +		install: get_option('enable_docs'),
> +		install_dir: htmldir,
> +		build_by_default: false)
> +
> +	run_target('doc', command: 'true', depends: doxy_build)
> +endif

Suggestion: add a run_target in an else leg to just print out "no
doxygen found" or similar message when ninja doc is called.

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson
  2018-09-10 15:47     ` Bruce Richardson
@ 2018-09-10 16:15       ` Luca Boccassi
  0 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 16:15 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Mon, 2018-09-10 at 16:47 +0100, Bruce Richardson wrote:
> On Fri, Sep 07, 2018 at 05:55:24PM +0100, Luca Boccassi wrote:
> > Signed-off-by: Luca Boccassi <bluca@debian.org>
> > ---
> > v2: made doxygen dependency optional, skip doxygen build when not
> > found
> > 
> >  doc/api/generate_doxygen.sh | 10 +++++++
> >  doc/api/meson.build         | 54
> > +++++++++++++++++++++++++++++++++++++
> >  doc/build-sdk-meson.txt     |  2 ++
> >  doc/meson.build             |  4 +++
> >  meson.build                 |  3 +++
> >  meson_options.txt           |  2 ++
> >  6 files changed, 75 insertions(+)
> >  create mode 100755 doc/api/generate_doxygen.sh
> >  create mode 100644 doc/api/meson.build
> >  create mode 100644 doc/meson.build
> > 
> > diff --git a/doc/api/generate_doxygen.sh
> > b/doc/api/generate_doxygen.sh
> > new file mode 100755
> > index 0000000000..ab57660958
> > --- /dev/null
> > +++ b/doc/api/generate_doxygen.sh
> > @@ -0,0 +1,10 @@
> > +#! /bin/sh -e
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +DOXYCONF=$1
> > +OUTDIR=$2
> > +SCRIPTCSS=$3
> > +
> > +doxygen "${DOXYCONF}"
> > +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> > diff --git a/doc/api/meson.build b/doc/api/meson.build
> > new file mode 100644
> > index 0000000000..5dfa0fe044
> > --- /dev/null
> > +++ b/doc/api/meson.build
> > @@ -0,0 +1,54 @@
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +doxygen = find_program('doxygen', required: false)
> 
> Thinking about it, I think that "required" should be set to
> "get_option(enable_docs)", since if someone explicitly enables the
> docs
> they should be built and cause error if they can't be.

Done in v3

> > +
> > +if doxygen.found()
> > +	# due to the CSS customisation script, which needs to run
> > on a file that
> > +	# is in a subdirectory that is created at build time and
> > thus it cannot
> > +	# be an individual custom_target, we need to wrap the
> > doxygen call in a
> > +	# script to run the CSS modification afterwards
> > +	generate_doxygen = find_program('generate_doxygen.sh')
> > +	generate_examples = find_program('generate_examples.sh')
> > +	generate_css = find_program('doxy-html-custom.sh')
> > +
> > +	inputdir = join_paths(meson.source_root(), 'examples')
> > +	htmldir = join_paths('doc', 'html')
> > +
> > +	# due to the following bug: https://github.com/mesonbuild/
> > meson/issues/4107
> > +	# if install is set to true it will override
> > build_by_default and it will
> > +	# cause the target to always be built. If install were to
> > be always set to
> > +	# false it would be impossible to install the docs.
> > +	# So use a configure option for now.
> > +	example = custom_target('examples.dox',
> > +		input: inputdir,
> > +		output: 'examples.dox',
> > +		command: [generate_examples, '@INPUT@', '@OUTPUT@'
> > ],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	cdata = configuration_data()
> > +	cdata.set('VERSION', meson.project_version())
> > +	cdata.set('API_EXAMPLES', join_paths(meson.build_root(),
> > 'doc', 'api', 'examples.dox'))
> > +	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc',
> > 'api'))
> > +	cdata.set('HTML_OUTPUT', 'api')
> > +	cdata.set('TOPDIR', meson.source_root())
> > +	cdata.set('STRIP_FROM_PATH', meson.source_root())
> > +
> > +	doxy_conf = configure_file(input: 'doxy-api.conf.in',
> > +		output: 'doxy-api.conf',
> > +		configuration: cdata,
> > +		install: false)
> > +
> > +	doxy_build = custom_target('doxygen',
> > +		depends: example,
> > +		input: doxy_conf,
> > +		output: 'api',
> > +		command: [generate_doxygen, '@INPUT@', '@OUTPUT@',
> > generate_css],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	run_target('doc', command: 'true', depends: doxy_build)
> > +endif
> 
> Suggestion: add a run_target in an else leg to just print out "no
> doxygen found" or similar message when ninja doc is called.

Done

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
                     ` (2 preceding siblings ...)
  2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-10 15:49   ` Bruce Richardson
  2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
  4 siblings, 0 replies; 39+ messages in thread
From: Bruce Richardson @ 2018-09-10 15:49 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Fri, Sep 07, 2018 at 05:55:21PM +0100, Luca Boccassi wrote:
> This will make it possible to generate the file in the same way from
> Meson as well.
> 
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> ---

Couple of comments on patch 4, otherwise looks ok to me.

Series-acked-by: Bruce Richardson <bruce.richardson@intel.com>

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v3 1/4] mk: use script to generate examples.dox
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
                     ` (3 preceding siblings ...)
  2018-09-10 15:49   ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Bruce Richardson
@ 2018-09-10 16:13   ` Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
                       ` (2 more replies)
  4 siblings, 3 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 16:13 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will make it possible to generate the file in the same way from
Meson as well.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: simplified script by using exec > file

 doc/api/generate_examples.sh | 12 ++++++++++++
 mk/rte.sdkdoc.mk             |  5 +----
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100755 doc/api/generate_examples.sh

diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
new file mode 100755
index 0000000000..6fcfe513b6
--- /dev/null
+++ b/doc/api/generate_examples.sh
@@ -0,0 +1,12 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+EXAMPLES_DIR=$1
+API_EXAMPLES=$2
+
+exec > "${API_EXAMPLES}"
+printf '/**\n'
+printf '@page examples DPDK Example Programs\n\n'
+find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort
+printf '*/\n'
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index bd2e5763df..d023b720fe 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -63,10 +63,7 @@ api-html-clean:
 
 $(API_EXAMPLES): api-html-clean
 	$(Q)mkdir -p $(@D)
-	@printf '/**\n' > $(API_EXAMPLES)
-	@printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES)
-	@find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES)
-	@printf '*/\n' >> $(API_EXAMPLES)
+	$(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES)
 
 guides-pdf-clean: guides-pdf-img-clean
 guides-pdf-img-clean:
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly
  2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
@ 2018-09-10 16:13     ` Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 3/4] build: use same version as make showversion in Meson Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 16:13 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will allow the same config file to be used from Meson.
The result has been verified to be identical via diffoscope.

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: reordered generated fields as requested

 doc/api/doxy-api.conf    | 87 ------------------------------------
 doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++
 mk/rte.sdkdoc.mk         | 16 +++----
 3 files changed, 103 insertions(+), 96 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
deleted file mode 100644
index 66693c3835..0000000000
--- a/doc/api/doxy-api.conf
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013-2017 6WIND S.A.
-
-PROJECT_NAME            = DPDK
-INPUT                   = doc/api/doxy-api-index.md \
-                          drivers/crypto/scheduler \
-                          drivers/mempool/dpaa2 \
-                          drivers/net/bnxt \
-                          drivers/net/bonding \
-                          drivers/net/dpaa \
-                          drivers/net/i40e \
-                          drivers/net/ixgbe \
-                          drivers/net/softnic \
-                          drivers/raw/dpaa2_cmdif \
-                          drivers/raw/dpaa2_qdma \
-                          lib/librte_eal/common/include \
-                          lib/librte_eal/common/include/generic \
-                          lib/librte_acl \
-                          lib/librte_bbdev \
-                          lib/librte_bitratestats \
-                          lib/librte_bpf \
-                          lib/librte_cfgfile \
-                          lib/librte_cmdline \
-                          lib/librte_compat \
-                          lib/librte_compressdev \
-                          lib/librte_cryptodev \
-                          lib/librte_distributor \
-                          lib/librte_efd \
-                          lib/librte_ethdev \
-                          lib/librte_eventdev \
-                          lib/librte_flow_classify \
-                          lib/librte_gro \
-                          lib/librte_gso \
-                          lib/librte_hash \
-                          lib/librte_ip_frag \
-                          lib/librte_jobstats \
-                          lib/librte_kni \
-                          lib/librte_kvargs \
-                          lib/librte_latencystats \
-                          lib/librte_lpm \
-                          lib/librte_mbuf \
-                          lib/librte_member \
-                          lib/librte_mempool \
-                          lib/librte_meter \
-                          lib/librte_metrics \
-                          lib/librte_net \
-                          lib/librte_pci \
-                          lib/librte_pdump \
-                          lib/librte_pipeline \
-                          lib/librte_port \
-                          lib/librte_power \
-                          lib/librte_rawdev \
-                          lib/librte_reorder \
-                          lib/librte_ring \
-                          lib/librte_sched \
-                          lib/librte_security \
-                          lib/librte_table \
-                          lib/librte_timer \
-                          lib/librte_vhost
-FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
-PREDEFINED              = __DOXYGEN__ \
-			   VFIO_PRESENT \
-                          __attribute__(x)=
-
-OPTIMIZE_OUTPUT_FOR_C   = YES
-ENABLE_PREPROCESSING    = YES
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_STATIC          = YES
-DISTRIBUTE_GROUP_DOC    = YES
-HIDE_UNDOC_MEMBERS      = YES
-HIDE_UNDOC_CLASSES      = YES
-HIDE_SCOPE_NAMES        = YES
-GENERATE_DEPRECATEDLIST = NO
-VERBATIM_HEADERS        = NO
-ALPHABETICAL_INDEX      = NO
-
-HTML_TIMESTAMP          = NO
-HTML_DYNAMIC_SECTIONS   = YES
-SEARCHENGINE            = NO
-SORT_MEMBER_DOCS        = NO
-SOURCE_BROWSER          = YES
-
-EXAMPLE_PATH            = examples
-EXAMPLE_PATTERNS        = *.c
-EXAMPLE_RECURSIVE       = YES
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
new file mode 100644
index 0000000000..c3d8fdef18
--- /dev/null
+++ b/doc/api/doxy-api.conf.in
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2013-2017 6WIND S.A.
+
+PROJECT_NAME            = DPDK
+PROJECT_NUMBER          = @VERSION@
+INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/crypto/scheduler \
+                          @TOPDIR@/drivers/mempool/dpaa2 \
+                          @TOPDIR@/drivers/net/bnxt \
+                          @TOPDIR@/drivers/net/bonding \
+                          @TOPDIR@/drivers/net/dpaa \
+                          @TOPDIR@/drivers/net/i40e \
+                          @TOPDIR@/drivers/net/ixgbe \
+                          @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
+                          @TOPDIR@/drivers/raw/dpaa2_qdma \
+                          @TOPDIR@/lib/librte_eal/common/include \
+                          @TOPDIR@/lib/librte_eal/common/include/generic \
+                          @TOPDIR@/lib/librte_acl \
+                          @TOPDIR@/lib/librte_bbdev \
+                          @TOPDIR@/lib/librte_bitratestats \
+                          @TOPDIR@/lib/librte_bpf \
+                          @TOPDIR@/lib/librte_cfgfile \
+                          @TOPDIR@/lib/librte_cmdline \
+                          @TOPDIR@/lib/librte_compat \
+                          @TOPDIR@/lib/librte_compressdev \
+                          @TOPDIR@/lib/librte_cryptodev \
+                          @TOPDIR@/lib/librte_distributor \
+                          @TOPDIR@/lib/librte_efd \
+                          @TOPDIR@/lib/librte_ethdev \
+                          @TOPDIR@/lib/librte_eventdev \
+                          @TOPDIR@/lib/librte_flow_classify \
+                          @TOPDIR@/lib/librte_gro \
+                          @TOPDIR@/lib/librte_gso \
+                          @TOPDIR@/lib/librte_hash \
+                          @TOPDIR@/lib/librte_ip_frag \
+                          @TOPDIR@/lib/librte_jobstats \
+                          @TOPDIR@/lib/librte_kni \
+                          @TOPDIR@/lib/librte_kvargs \
+                          @TOPDIR@/lib/librte_latencystats \
+                          @TOPDIR@/lib/librte_lpm \
+                          @TOPDIR@/lib/librte_mbuf \
+                          @TOPDIR@/lib/librte_member \
+                          @TOPDIR@/lib/librte_mempool \
+                          @TOPDIR@/lib/librte_meter \
+                          @TOPDIR@/lib/librte_metrics \
+                          @TOPDIR@/lib/librte_net \
+                          @TOPDIR@/lib/librte_pci \
+                          @TOPDIR@/lib/librte_pdump \
+                          @TOPDIR@/lib/librte_pipeline \
+                          @TOPDIR@/lib/librte_port \
+                          @TOPDIR@/lib/librte_power \
+                          @TOPDIR@/lib/librte_rawdev \
+                          @TOPDIR@/lib/librte_reorder \
+                          @TOPDIR@/lib/librte_ring \
+                          @TOPDIR@/lib/librte_sched \
+                          @TOPDIR@/lib/librte_security \
+                          @TOPDIR@/lib/librte_table \
+                          @TOPDIR@/lib/librte_timer \
+                          @TOPDIR@/lib/librte_vhost
+INPUT                   += @API_EXAMPLES@
+FILE_PATTERNS           = rte_*.h \
+                          cmdline.h
+PREDEFINED              = __DOXYGEN__ \
+			   VFIO_PRESENT \
+                          __attribute__(x)=
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_STATIC          = YES
+DISTRIBUTE_GROUP_DOC    = YES
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_SCOPE_NAMES        = YES
+GENERATE_DEPRECATEDLIST = NO
+VERBATIM_HEADERS        = NO
+ALPHABETICAL_INDEX      = NO
+
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = YES
+SEARCHENGINE            = NO
+SORT_MEMBER_DOCS        = NO
+SOURCE_BROWSER          = YES
+
+EXAMPLE_PATH            = @TOPDIR@/examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
+
+OUTPUT_DIRECTORY        = @OUTPUT@
+STRIP_FROM_PATH         = @STRIP_FROM_PATH@
+GENERATE_HTML           = YES
+HTML_OUTPUT             = @HTML_OUTPUT@
+GENERATE_LATEX          = NO
+GENERATE_MAN            = NO
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index d023b720fe..c44db6447a 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
 api-html: $(API_EXAMPLES)
 	@echo 'doxygen for API...'
 	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
-	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
-	    printf 'PROJECT_NUMBER = '                && \
-	                     $(MAKE) -rRs showversion && \
-	    echo INPUT           += $(API_EXAMPLES)   && \
-	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
-	    echo HTML_OUTPUT      = html/api          && \
-	    echo GENERATE_HTML    = YES               && \
-	    echo GENERATE_LATEX   = NO                && \
-	    echo GENERATE_MAN     = NO                )| \
+	$(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \
+	         -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|"       \
+	         -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|"           \
+	         -e "s|@HTML_OUTPUT@|html/api|"               \
+	         -e "s|@TOPDIR@|./|g"                         \
+	         -e "s|@STRIP_FROM_PATH@|./|g"                \
+	         $(RTE_SDK)/doc/api/doxy-api.conf.in)|        \
 	    doxygen -
 	$(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
 
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v3 3/4] build: use same version as make showversion in Meson
  2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-09-10 16:13     ` Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 16:13 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
causing among other things a difference in the generated documentation.

Fixes: 76b9d9de5c7d ("version: 18.11-rc0")

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index 84af32ecef..9999e8640a 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # Copyright(c) 2017 Intel Corporation
 
 project('DPDK', 'C',
-	version: '18.11-rc0',
+	version: '18.11.0-rc0',
 	license: 'BSD',
 	default_options: ['buildtype=release', 'default_library=static'],
 	meson_version: '>= 0.41'
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson
  2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-09-10 16:13     ` Luca Boccassi
  2018-09-10 17:30       ` Bruce Richardson
  2 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 16:13 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

Signed-off-by: Luca Boccassi <bluca@debian.org>
---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory if enable_docs is true, add
    alternative doc target that prints "doxygen not found" when doxygen
    is not found and enable_docs is false (default)

 doc/api/generate_doxygen.sh | 10 +++++++
 doc/api/meson.build         | 56 +++++++++++++++++++++++++++++++++++++
 doc/build-sdk-meson.txt     |  2 ++
 doc/meson.build             |  4 +++
 meson.build                 |  3 ++
 meson_options.txt           |  2 ++
 6 files changed, 77 insertions(+)
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..602fa7f3c3
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+doxygen = find_program('doxygen', required: get_option('enable_docs'))
+
+if doxygen.found()
+	# due to the CSS customisation script, which needs to run on a file that
+	# is in a subdirectory that is created at build time and thus it cannot
+	# be an individual custom_target, we need to wrap the doxygen call in a
+	# script to run the CSS modification afterwards
+	generate_doxygen = find_program('generate_doxygen.sh')
+	generate_examples = find_program('generate_examples.sh')
+	generate_css = find_program('doxy-html-custom.sh')
+
+	inputdir = join_paths(meson.source_root(), 'examples')
+	htmldir = join_paths('doc', 'html')
+
+	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+	# if install is set to true it will override build_by_default and it will
+	# cause the target to always be built. If install were to be always set to
+	# false it would be impossible to install the docs.
+	# So use a configure option for now.
+	example = custom_target('examples.dox',
+		input: inputdir,
+		output: 'examples.dox',
+		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	cdata = configuration_data()
+	cdata.set('VERSION', meson.project_version())
+	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
+	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
+	cdata.set('HTML_OUTPUT', 'api')
+	cdata.set('TOPDIR', meson.source_root())
+	cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+	doxy_conf = configure_file(input: 'doxy-api.conf.in',
+		output: 'doxy-api.conf',
+		configuration: cdata,
+		install: false)
+
+	doxy_build = custom_target('doxygen',
+		depends: example,
+		input: doxy_conf,
+		output: 'api',
+		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	run_target('doc', command: 'true', depends: doxy_build)
+else
+	run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
+endif
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
 
 	meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
 
+	meson -Denable_docs=true fullbuild  # build and install docs
+
 Examples of setting the same options using meson configure::
 
 	meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
 subdir('app')
 subdir('test')
 
+# build docs
+subdir('doc')
+
 # build any examples explicitly requested - useful for developers
 if get_option('examples') != ''
 	subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
 	description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
 option('enable_kmods', type: 'boolean', value: true,
 	description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+	description: 'build documentation')
 option('examples', type: 'string', value: '',
 	description: 'Comma-separated list of examples to build by default')
 option('include_subdir_arch', type: 'string', value: '',
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson
  2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-10 17:30       ` Bruce Richardson
  2018-09-10 17:32         ` Bruce Richardson
  2018-09-10 17:35         ` Luca Boccassi
  0 siblings, 2 replies; 39+ messages in thread
From: Bruce Richardson @ 2018-09-10 17:30 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote:
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> ---
> v2: made doxygen dependency optional, skip doxygen build when not found
> v3: made doxygen dependency mandatory if enable_docs is true, add
>     alternative doc target that prints "doxygen not found" when doxygen
>     is not found and enable_docs is false (default)
> 
>  doc/api/generate_doxygen.sh | 10 +++++++
>  doc/api/meson.build         | 56 +++++++++++++++++++++++++++++++++++++
>  doc/build-sdk-meson.txt     |  2 ++
>  doc/meson.build             |  4 +++
>  meson.build                 |  3 ++
>  meson_options.txt           |  2 ++
>  6 files changed, 77 insertions(+)
>  create mode 100755 doc/api/generate_doxygen.sh
>  create mode 100644 doc/api/meson.build
>  create mode 100644 doc/meson.build
> 
> diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
> new file mode 100755
> index 0000000000..ab57660958
> --- /dev/null
> +++ b/doc/api/generate_doxygen.sh
> @@ -0,0 +1,10 @@
> +#! /bin/sh -e
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> +
> +DOXYCONF=$1
> +OUTDIR=$2
> +SCRIPTCSS=$3
> +
> +doxygen "${DOXYCONF}"
> +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> diff --git a/doc/api/meson.build b/doc/api/meson.build
> new file mode 100644
> index 0000000000..602fa7f3c3
> --- /dev/null
> +++ b/doc/api/meson.build
> @@ -0,0 +1,56 @@
> +# SPDX-License-Identifier: BSD-3-Clause
> +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> +
> +doxygen = find_program('doxygen', required: get_option('enable_docs'))
> +
> +if doxygen.found()
> +	# due to the CSS customisation script, which needs to run on a file that
> +	# is in a subdirectory that is created at build time and thus it cannot
> +	# be an individual custom_target, we need to wrap the doxygen call in a
> +	# script to run the CSS modification afterwards
> +	generate_doxygen = find_program('generate_doxygen.sh')
> +	generate_examples = find_program('generate_examples.sh')
> +	generate_css = find_program('doxy-html-custom.sh')
> +
> +	inputdir = join_paths(meson.source_root(), 'examples')
> +	htmldir = join_paths('doc', 'html')
> +
> +	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
> +	# if install is set to true it will override build_by_default and it will
> +	# cause the target to always be built. If install were to be always set to
> +	# false it would be impossible to install the docs.
> +	# So use a configure option for now.
> +	example = custom_target('examples.dox',
> +		input: inputdir,
> +		output: 'examples.dox',
> +		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
> +		install: get_option('enable_docs'),
> +		install_dir: htmldir,
> +		build_by_default: false)
> +
> +	cdata = configuration_data()
> +	cdata.set('VERSION', meson.project_version())
> +	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
> +	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
> +	cdata.set('HTML_OUTPUT', 'api')
> +	cdata.set('TOPDIR', meson.source_root())
> +	cdata.set('STRIP_FROM_PATH', meson.source_root())
> +
> +	doxy_conf = configure_file(input: 'doxy-api.conf.in',
> +		output: 'doxy-api.conf',
> +		configuration: cdata,
> +		install: false)
> +
> +	doxy_build = custom_target('doxygen',
> +		depends: example,
> +		input: doxy_conf,
> +		output: 'api',
> +		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
> +		install: get_option('enable_docs'),
> +		install_dir: htmldir,
> +		build_by_default: false)
> +
> +	run_target('doc', command: 'true', depends: doxy_build)
> +else
> +	run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
> +endif

While I suggest we keep this in this patchset for now, this isn't going to
scale as we add in more targets for building the PDF/HTML guides. I think
for that case, we may need to use an array variable for the "depends"
target, and add things to that as we process the documentation meson.build
files. That might work better for cases where we have some but not all doc
build capabilities, e.g. missing sphinx but not doxygen.

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson
  2018-09-10 17:30       ` Bruce Richardson
@ 2018-09-10 17:32         ` Bruce Richardson
  2018-09-10 17:35         ` Luca Boccassi
  1 sibling, 0 replies; 39+ messages in thread
From: Bruce Richardson @ 2018-09-10 17:32 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Mon, Sep 10, 2018 at 06:30:51PM +0100, Bruce Richardson wrote:
> On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote:
> > Signed-off-by: Luca Boccassi <bluca@debian.org>
> > ---
> > v2: made doxygen dependency optional, skip doxygen build when not found
> > v3: made doxygen dependency mandatory if enable_docs is true, add
> >     alternative doc target that prints "doxygen not found" when doxygen
> >     is not found and enable_docs is false (default)
> > 
> >  doc/api/generate_doxygen.sh | 10 +++++++
> >  doc/api/meson.build         | 56 +++++++++++++++++++++++++++++++++++++
> >  doc/build-sdk-meson.txt     |  2 ++
> >  doc/meson.build             |  4 +++
> >  meson.build                 |  3 ++
> >  meson_options.txt           |  2 ++
> >  6 files changed, 77 insertions(+)
> >  create mode 100755 doc/api/generate_doxygen.sh
> >  create mode 100644 doc/api/meson.build
> >  create mode 100644 doc/meson.build
> > 
> > diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
> > new file mode 100755
> > index 0000000000..ab57660958
> > --- /dev/null
> > +++ b/doc/api/generate_doxygen.sh
> > @@ -0,0 +1,10 @@
> > +#! /bin/sh -e
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +DOXYCONF=$1
> > +OUTDIR=$2
> > +SCRIPTCSS=$3
> > +
> > +doxygen "${DOXYCONF}"
> > +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> > diff --git a/doc/api/meson.build b/doc/api/meson.build
> > new file mode 100644
> > index 0000000000..602fa7f3c3
> > --- /dev/null
> > +++ b/doc/api/meson.build
> > @@ -0,0 +1,56 @@
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +doxygen = find_program('doxygen', required: get_option('enable_docs'))
> > +
> > +if doxygen.found()
> > +	# due to the CSS customisation script, which needs to run on a file that
> > +	# is in a subdirectory that is created at build time and thus it cannot
> > +	# be an individual custom_target, we need to wrap the doxygen call in a
> > +	# script to run the CSS modification afterwards
> > +	generate_doxygen = find_program('generate_doxygen.sh')
> > +	generate_examples = find_program('generate_examples.sh')
> > +	generate_css = find_program('doxy-html-custom.sh')
> > +
> > +	inputdir = join_paths(meson.source_root(), 'examples')
> > +	htmldir = join_paths('doc', 'html')
> > +
> > +	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
> > +	# if install is set to true it will override build_by_default and it will
> > +	# cause the target to always be built. If install were to be always set to
> > +	# false it would be impossible to install the docs.
> > +	# So use a configure option for now.
> > +	example = custom_target('examples.dox',
> > +		input: inputdir,
> > +		output: 'examples.dox',
> > +		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	cdata = configuration_data()
> > +	cdata.set('VERSION', meson.project_version())
> > +	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
> > +	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
> > +	cdata.set('HTML_OUTPUT', 'api')
> > +	cdata.set('TOPDIR', meson.source_root())
> > +	cdata.set('STRIP_FROM_PATH', meson.source_root())
> > +
> > +	doxy_conf = configure_file(input: 'doxy-api.conf.in',
> > +		output: 'doxy-api.conf',
> > +		configuration: cdata,
> > +		install: false)
> > +
> > +	doxy_build = custom_target('doxygen',
> > +		depends: example,
> > +		input: doxy_conf,
> > +		output: 'api',
> > +		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	run_target('doc', command: 'true', depends: doxy_build)
> > +else
> > +	run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
> > +endif
> 
> While I suggest we keep this in this patchset for now, this isn't going to
> scale as we add in more targets for building the PDF/HTML guides. I think
> for that case, we may need to use an array variable for the "depends"
> target, and add things to that as we process the documentation meson.build
> files. That might work better for cases where we have some but not all doc
> build capabilities, e.g. missing sphinx but not doxygen.

And the main reason I don't recommend changing this yet, is that until we
add in the extra doc builds we probably won't know what the result needs to
look like anyway, so little point in just guessing what the solution would
be.

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson
  2018-09-10 17:30       ` Bruce Richardson
  2018-09-10 17:32         ` Bruce Richardson
@ 2018-09-10 17:35         ` Luca Boccassi
  1 sibling, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 17:35 UTC (permalink / raw)
  To: Bruce Richardson; +Cc: dev, john.mcnamara, marko.kovacevic, thomas

On Mon, 2018-09-10 at 18:30 +0100, Bruce Richardson wrote:
> On Mon, Sep 10, 2018 at 05:13:06PM +0100, Luca Boccassi wrote:
> > Signed-off-by: Luca Boccassi <bluca@debian.org>
> > ---
> > v2: made doxygen dependency optional, skip doxygen build when not
> > found
> > v3: made doxygen dependency mandatory if enable_docs is true, add
> >     alternative doc target that prints "doxygen not found" when
> > doxygen
> >     is not found and enable_docs is false (default)
> > 
> >  doc/api/generate_doxygen.sh | 10 +++++++
> >  doc/api/meson.build         | 56
> > +++++++++++++++++++++++++++++++++++++
> >  doc/build-sdk-meson.txt     |  2 ++
> >  doc/meson.build             |  4 +++
> >  meson.build                 |  3 ++
> >  meson_options.txt           |  2 ++
> >  6 files changed, 77 insertions(+)
> >  create mode 100755 doc/api/generate_doxygen.sh
> >  create mode 100644 doc/api/meson.build
> >  create mode 100644 doc/meson.build
> > 
> > diff --git a/doc/api/generate_doxygen.sh
> > b/doc/api/generate_doxygen.sh
> > new file mode 100755
> > index 0000000000..ab57660958
> > --- /dev/null
> > +++ b/doc/api/generate_doxygen.sh
> > @@ -0,0 +1,10 @@
> > +#! /bin/sh -e
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +DOXYCONF=$1
> > +OUTDIR=$2
> > +SCRIPTCSS=$3
> > +
> > +doxygen "${DOXYCONF}"
> > +"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
> > diff --git a/doc/api/meson.build b/doc/api/meson.build
> > new file mode 100644
> > index 0000000000..602fa7f3c3
> > --- /dev/null
> > +++ b/doc/api/meson.build
> > @@ -0,0 +1,56 @@
> > +# SPDX-License-Identifier: BSD-3-Clause
> > +# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
> > +
> > +doxygen = find_program('doxygen', required:
> > get_option('enable_docs'))
> > +
> > +if doxygen.found()
> > +	# due to the CSS customisation script, which needs to run
> > on a file that
> > +	# is in a subdirectory that is created at build time and
> > thus it cannot
> > +	# be an individual custom_target, we need to wrap the
> > doxygen call in a
> > +	# script to run the CSS modification afterwards
> > +	generate_doxygen = find_program('generate_doxygen.sh')
> > +	generate_examples = find_program('generate_examples.sh')
> > +	generate_css = find_program('doxy-html-custom.sh')
> > +
> > +	inputdir = join_paths(meson.source_root(), 'examples')
> > +	htmldir = join_paths('doc', 'html')
> > +
> > +	# due to the following bug: https://github.com/mesonbuild/
> > meson/issues/4107
> > +	# if install is set to true it will override
> > build_by_default and it will
> > +	# cause the target to always be built. If install were to
> > be always set to
> > +	# false it would be impossible to install the docs.
> > +	# So use a configure option for now.
> > +	example = custom_target('examples.dox',
> > +		input: inputdir,
> > +		output: 'examples.dox',
> > +		command: [generate_examples, '@INPUT@', '@OUTPUT@'
> > ],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	cdata = configuration_data()
> > +	cdata.set('VERSION', meson.project_version())
> > +	cdata.set('API_EXAMPLES', join_paths(meson.build_root(),
> > 'doc', 'api', 'examples.dox'))
> > +	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc',
> > 'api'))
> > +	cdata.set('HTML_OUTPUT', 'api')
> > +	cdata.set('TOPDIR', meson.source_root())
> > +	cdata.set('STRIP_FROM_PATH', meson.source_root())
> > +
> > +	doxy_conf = configure_file(input: 'doxy-api.conf.in',
> > +		output: 'doxy-api.conf',
> > +		configuration: cdata,
> > +		install: false)
> > +
> > +	doxy_build = custom_target('doxygen',
> > +		depends: example,
> > +		input: doxy_conf,
> > +		output: 'api',
> > +		command: [generate_doxygen, '@INPUT@', '@OUTPUT@',
> > generate_css],
> > +		install: get_option('enable_docs'),
> > +		install_dir: htmldir,
> > +		build_by_default: false)
> > +
> > +	run_target('doc', command: 'true', depends: doxy_build)
> > +else
> > +	run_target('doc', command: ['echo', 'doxygen', 'not',
> > 'found'])
> > +endif
> 
> While I suggest we keep this in this patchset for now, this isn't
> going to
> scale as we add in more targets for building the PDF/HTML guides. I
> think
> for that case, we may need to use an array variable for the "depends"
> target, and add things to that as we process the documentation
> meson.build
> files. That might work better for cases where we have some but not
> all doc
> build capabilities, e.g. missing sphinx but not doxygen.

Yeah that makes sense, I can rework that once the sphinx stuff is also
in.

Did you manage to get it working yet?

-- 
Kind regards,
Luca Boccassi

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
                   ` (4 preceding siblings ...)
  2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-10 20:09 ` Luca Boccassi
  2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
                     ` (2 more replies)
  2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
  6 siblings, 3 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 20:09 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will make it possible to generate the file in the same way from
Meson as well.

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: simplified script by using exec > file
v4: add acked-by

 doc/api/generate_examples.sh | 12 ++++++++++++
 mk/rte.sdkdoc.mk             |  5 +----
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100755 doc/api/generate_examples.sh

diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
new file mode 100755
index 0000000000..6fcfe513b6
--- /dev/null
+++ b/doc/api/generate_examples.sh
@@ -0,0 +1,12 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+EXAMPLES_DIR=$1
+API_EXAMPLES=$2
+
+exec > "${API_EXAMPLES}"
+printf '/**\n'
+printf '@page examples DPDK Example Programs\n\n'
+find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort
+printf '*/\n'
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index bd2e5763df..d023b720fe 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -63,10 +63,7 @@ api-html-clean:
 
 $(API_EXAMPLES): api-html-clean
 	$(Q)mkdir -p $(@D)
-	@printf '/**\n' > $(API_EXAMPLES)
-	@printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES)
-	@find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES)
-	@printf '*/\n' >> $(API_EXAMPLES)
+	$(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES)
 
 guides-pdf-clean: guides-pdf-img-clean
 guides-pdf-img-clean:
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly
  2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-10 20:09   ` Luca Boccassi
  2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 3/4] build: use same version as make showversion in Meson Luca Boccassi
  2018-09-10 20:10   ` [dpdk-dev] [PATCH v4 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 20:09 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will allow the same config file to be used from Meson.
The result has been verified to be identical via diffoscope.

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: reordered generated fields as requested
v4: add acked-by

 doc/api/doxy-api.conf    | 87 ------------------------------------
 doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++
 mk/rte.sdkdoc.mk         | 16 +++----
 3 files changed, 103 insertions(+), 96 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
deleted file mode 100644
index 66693c3835..0000000000
--- a/doc/api/doxy-api.conf
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013-2017 6WIND S.A.
-
-PROJECT_NAME            = DPDK
-INPUT                   = doc/api/doxy-api-index.md \
-                          drivers/crypto/scheduler \
-                          drivers/mempool/dpaa2 \
-                          drivers/net/bnxt \
-                          drivers/net/bonding \
-                          drivers/net/dpaa \
-                          drivers/net/i40e \
-                          drivers/net/ixgbe \
-                          drivers/net/softnic \
-                          drivers/raw/dpaa2_cmdif \
-                          drivers/raw/dpaa2_qdma \
-                          lib/librte_eal/common/include \
-                          lib/librte_eal/common/include/generic \
-                          lib/librte_acl \
-                          lib/librte_bbdev \
-                          lib/librte_bitratestats \
-                          lib/librte_bpf \
-                          lib/librte_cfgfile \
-                          lib/librte_cmdline \
-                          lib/librte_compat \
-                          lib/librte_compressdev \
-                          lib/librte_cryptodev \
-                          lib/librte_distributor \
-                          lib/librte_efd \
-                          lib/librte_ethdev \
-                          lib/librte_eventdev \
-                          lib/librte_flow_classify \
-                          lib/librte_gro \
-                          lib/librte_gso \
-                          lib/librte_hash \
-                          lib/librte_ip_frag \
-                          lib/librte_jobstats \
-                          lib/librte_kni \
-                          lib/librte_kvargs \
-                          lib/librte_latencystats \
-                          lib/librte_lpm \
-                          lib/librte_mbuf \
-                          lib/librte_member \
-                          lib/librte_mempool \
-                          lib/librte_meter \
-                          lib/librte_metrics \
-                          lib/librte_net \
-                          lib/librte_pci \
-                          lib/librte_pdump \
-                          lib/librte_pipeline \
-                          lib/librte_port \
-                          lib/librte_power \
-                          lib/librte_rawdev \
-                          lib/librte_reorder \
-                          lib/librte_ring \
-                          lib/librte_sched \
-                          lib/librte_security \
-                          lib/librte_table \
-                          lib/librte_timer \
-                          lib/librte_vhost
-FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
-PREDEFINED              = __DOXYGEN__ \
-			   VFIO_PRESENT \
-                          __attribute__(x)=
-
-OPTIMIZE_OUTPUT_FOR_C   = YES
-ENABLE_PREPROCESSING    = YES
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_STATIC          = YES
-DISTRIBUTE_GROUP_DOC    = YES
-HIDE_UNDOC_MEMBERS      = YES
-HIDE_UNDOC_CLASSES      = YES
-HIDE_SCOPE_NAMES        = YES
-GENERATE_DEPRECATEDLIST = NO
-VERBATIM_HEADERS        = NO
-ALPHABETICAL_INDEX      = NO
-
-HTML_TIMESTAMP          = NO
-HTML_DYNAMIC_SECTIONS   = YES
-SEARCHENGINE            = NO
-SORT_MEMBER_DOCS        = NO
-SOURCE_BROWSER          = YES
-
-EXAMPLE_PATH            = examples
-EXAMPLE_PATTERNS        = *.c
-EXAMPLE_RECURSIVE       = YES
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
new file mode 100644
index 0000000000..c3d8fdef18
--- /dev/null
+++ b/doc/api/doxy-api.conf.in
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2013-2017 6WIND S.A.
+
+PROJECT_NAME            = DPDK
+PROJECT_NUMBER          = @VERSION@
+INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/crypto/scheduler \
+                          @TOPDIR@/drivers/mempool/dpaa2 \
+                          @TOPDIR@/drivers/net/bnxt \
+                          @TOPDIR@/drivers/net/bonding \
+                          @TOPDIR@/drivers/net/dpaa \
+                          @TOPDIR@/drivers/net/i40e \
+                          @TOPDIR@/drivers/net/ixgbe \
+                          @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
+                          @TOPDIR@/drivers/raw/dpaa2_qdma \
+                          @TOPDIR@/lib/librte_eal/common/include \
+                          @TOPDIR@/lib/librte_eal/common/include/generic \
+                          @TOPDIR@/lib/librte_acl \
+                          @TOPDIR@/lib/librte_bbdev \
+                          @TOPDIR@/lib/librte_bitratestats \
+                          @TOPDIR@/lib/librte_bpf \
+                          @TOPDIR@/lib/librte_cfgfile \
+                          @TOPDIR@/lib/librte_cmdline \
+                          @TOPDIR@/lib/librte_compat \
+                          @TOPDIR@/lib/librte_compressdev \
+                          @TOPDIR@/lib/librte_cryptodev \
+                          @TOPDIR@/lib/librte_distributor \
+                          @TOPDIR@/lib/librte_efd \
+                          @TOPDIR@/lib/librte_ethdev \
+                          @TOPDIR@/lib/librte_eventdev \
+                          @TOPDIR@/lib/librte_flow_classify \
+                          @TOPDIR@/lib/librte_gro \
+                          @TOPDIR@/lib/librte_gso \
+                          @TOPDIR@/lib/librte_hash \
+                          @TOPDIR@/lib/librte_ip_frag \
+                          @TOPDIR@/lib/librte_jobstats \
+                          @TOPDIR@/lib/librte_kni \
+                          @TOPDIR@/lib/librte_kvargs \
+                          @TOPDIR@/lib/librte_latencystats \
+                          @TOPDIR@/lib/librte_lpm \
+                          @TOPDIR@/lib/librte_mbuf \
+                          @TOPDIR@/lib/librte_member \
+                          @TOPDIR@/lib/librte_mempool \
+                          @TOPDIR@/lib/librte_meter \
+                          @TOPDIR@/lib/librte_metrics \
+                          @TOPDIR@/lib/librte_net \
+                          @TOPDIR@/lib/librte_pci \
+                          @TOPDIR@/lib/librte_pdump \
+                          @TOPDIR@/lib/librte_pipeline \
+                          @TOPDIR@/lib/librte_port \
+                          @TOPDIR@/lib/librte_power \
+                          @TOPDIR@/lib/librte_rawdev \
+                          @TOPDIR@/lib/librte_reorder \
+                          @TOPDIR@/lib/librte_ring \
+                          @TOPDIR@/lib/librte_sched \
+                          @TOPDIR@/lib/librte_security \
+                          @TOPDIR@/lib/librte_table \
+                          @TOPDIR@/lib/librte_timer \
+                          @TOPDIR@/lib/librte_vhost
+INPUT                   += @API_EXAMPLES@
+FILE_PATTERNS           = rte_*.h \
+                          cmdline.h
+PREDEFINED              = __DOXYGEN__ \
+			   VFIO_PRESENT \
+                          __attribute__(x)=
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_STATIC          = YES
+DISTRIBUTE_GROUP_DOC    = YES
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_SCOPE_NAMES        = YES
+GENERATE_DEPRECATEDLIST = NO
+VERBATIM_HEADERS        = NO
+ALPHABETICAL_INDEX      = NO
+
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = YES
+SEARCHENGINE            = NO
+SORT_MEMBER_DOCS        = NO
+SOURCE_BROWSER          = YES
+
+EXAMPLE_PATH            = @TOPDIR@/examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
+
+OUTPUT_DIRECTORY        = @OUTPUT@
+STRIP_FROM_PATH         = @STRIP_FROM_PATH@
+GENERATE_HTML           = YES
+HTML_OUTPUT             = @HTML_OUTPUT@
+GENERATE_LATEX          = NO
+GENERATE_MAN            = NO
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index d023b720fe..c44db6447a 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
 api-html: $(API_EXAMPLES)
 	@echo 'doxygen for API...'
 	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
-	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
-	    printf 'PROJECT_NUMBER = '                && \
-	                     $(MAKE) -rRs showversion && \
-	    echo INPUT           += $(API_EXAMPLES)   && \
-	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
-	    echo HTML_OUTPUT      = html/api          && \
-	    echo GENERATE_HTML    = YES               && \
-	    echo GENERATE_LATEX   = NO                && \
-	    echo GENERATE_MAN     = NO                )| \
+	$(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \
+	         -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|"       \
+	         -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|"           \
+	         -e "s|@HTML_OUTPUT@|html/api|"               \
+	         -e "s|@TOPDIR@|./|g"                         \
+	         -e "s|@STRIP_FROM_PATH@|./|g"                \
+	         $(RTE_SDK)/doc/api/doxy-api.conf.in)|        \
 	    doxygen -
 	$(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
 
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v4 3/4] build: use same version as make showversion in Meson
  2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-09-10 20:09   ` Luca Boccassi
  2018-09-10 20:10   ` [dpdk-dev] [PATCH v4 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 20:09 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
causing among other things a difference in the generated documentation.

Fixes: 76b9d9de5c7d ("version: 18.11-rc0")

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v3: add acked-by

 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index 84af32ecef..9999e8640a 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # Copyright(c) 2017 Intel Corporation
 
 project('DPDK', 'C',
-	version: '18.11-rc0',
+	version: '18.11.0-rc0',
 	license: 'BSD',
 	default_options: ['buildtype=release', 'default_library=static'],
 	meson_version: '>= 0.41'
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v4 4/4] build: generate API documentation with Meson
  2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
  2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-09-10 20:10   ` Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-10 20:10 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory if enable_docs is true, add
    alternative doc target that prints "doxygen not found" when doxygen
    is not found and enable_docs is false (default)
v4: add acked-by

 doc/api/generate_doxygen.sh | 10 +++++++
 doc/api/meson.build         | 56 +++++++++++++++++++++++++++++++++++++
 doc/build-sdk-meson.txt     |  2 ++
 doc/meson.build             |  4 +++
 meson.build                 |  3 ++
 meson_options.txt           |  2 ++
 6 files changed, 77 insertions(+)
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..602fa7f3c3
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+doxygen = find_program('doxygen', required: get_option('enable_docs'))
+
+if doxygen.found()
+	# due to the CSS customisation script, which needs to run on a file that
+	# is in a subdirectory that is created at build time and thus it cannot
+	# be an individual custom_target, we need to wrap the doxygen call in a
+	# script to run the CSS modification afterwards
+	generate_doxygen = find_program('generate_doxygen.sh')
+	generate_examples = find_program('generate_examples.sh')
+	generate_css = find_program('doxy-html-custom.sh')
+
+	inputdir = join_paths(meson.source_root(), 'examples')
+	htmldir = join_paths('doc', 'html')
+
+	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+	# if install is set to true it will override build_by_default and it will
+	# cause the target to always be built. If install were to be always set to
+	# false it would be impossible to install the docs.
+	# So use a configure option for now.
+	example = custom_target('examples.dox',
+		input: inputdir,
+		output: 'examples.dox',
+		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	cdata = configuration_data()
+	cdata.set('VERSION', meson.project_version())
+	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
+	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
+	cdata.set('HTML_OUTPUT', 'api')
+	cdata.set('TOPDIR', meson.source_root())
+	cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+	doxy_conf = configure_file(input: 'doxy-api.conf.in',
+		output: 'doxy-api.conf',
+		configuration: cdata,
+		install: false)
+
+	doxy_build = custom_target('doxygen',
+		depends: example,
+		input: doxy_conf,
+		output: 'api',
+		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	run_target('doc', command: 'true', depends: doxy_build)
+else
+	run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
+endif
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
 
 	meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
 
+	meson -Denable_docs=true fullbuild  # build and install docs
+
 Examples of setting the same options using meson configure::
 
 	meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
 subdir('app')
 subdir('test')
 
+# build docs
+subdir('doc')
+
 # build any examples explicitly requested - useful for developers
 if get_option('examples') != ''
 	subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
 	description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
 option('enable_kmods', type: 'boolean', value: true,
 	description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+	description: 'build documentation')
 option('examples', type: 'string', value: '',
 	description: 'Comma-separated list of examples to build by default')
 option('include_subdir_arch', type: 'string', value: '',
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox
  2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
                   ` (5 preceding siblings ...)
  2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-11 20:42 ` Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
                     ` (2 more replies)
  6 siblings, 3 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-11 20:42 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will make it possible to generate the file in the same way from
Meson as well.

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: simplified script by using exec > file
v4: add acked-by

 doc/api/generate_examples.sh | 12 ++++++++++++
 mk/rte.sdkdoc.mk             |  5 +----
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100755 doc/api/generate_examples.sh

diff --git a/doc/api/generate_examples.sh b/doc/api/generate_examples.sh
new file mode 100755
index 0000000000..6fcfe513b6
--- /dev/null
+++ b/doc/api/generate_examples.sh
@@ -0,0 +1,12 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+EXAMPLES_DIR=$1
+API_EXAMPLES=$2
+
+exec > "${API_EXAMPLES}"
+printf '/**\n'
+printf '@page examples DPDK Example Programs\n\n'
+find "${EXAMPLES_DIR}" -type f -name '*.c' -printf '@example examples/%P\n' | LC_ALL=C sort
+printf '*/\n'
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index bd2e5763df..d023b720fe 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -63,10 +63,7 @@ api-html-clean:
 
 $(API_EXAMPLES): api-html-clean
 	$(Q)mkdir -p $(@D)
-	@printf '/**\n' > $(API_EXAMPLES)
-	@printf '@page examples DPDK Example Programs\n\n' >> $(API_EXAMPLES)
-	@find examples -type f -name '*.c' -printf '@example %p\n' | LC_ALL=C sort >> $(API_EXAMPLES)
-	@printf '*/\n' >> $(API_EXAMPLES)
+	$(Q)doc/api/generate_examples.sh examples $(API_EXAMPLES)
 
 guides-pdf-clean: guides-pdf-img-clean
 guides-pdf-img-clean:
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly
  2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
@ 2018-09-11 20:42   ` Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 3/4] build: use same version as make showversion in Meson Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-11 20:42 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

This will allow the same config file to be used from Meson.
The result has been verified to be identical via diffoscope.

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: reordered generated fields as requested
v4: add acked-by

 doc/api/doxy-api.conf    | 87 ------------------------------------
 doc/api/doxy-api.conf.in | 96 ++++++++++++++++++++++++++++++++++++++++
 mk/rte.sdkdoc.mk         | 16 +++----
 3 files changed, 103 insertions(+), 96 deletions(-)
 delete mode 100644 doc/api/doxy-api.conf
 create mode 100644 doc/api/doxy-api.conf.in

diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf
deleted file mode 100644
index 66693c3835..0000000000
--- a/doc/api/doxy-api.conf
+++ /dev/null
@@ -1,87 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-# Copyright 2013-2017 6WIND S.A.
-
-PROJECT_NAME            = DPDK
-INPUT                   = doc/api/doxy-api-index.md \
-                          drivers/crypto/scheduler \
-                          drivers/mempool/dpaa2 \
-                          drivers/net/bnxt \
-                          drivers/net/bonding \
-                          drivers/net/dpaa \
-                          drivers/net/i40e \
-                          drivers/net/ixgbe \
-                          drivers/net/softnic \
-                          drivers/raw/dpaa2_cmdif \
-                          drivers/raw/dpaa2_qdma \
-                          lib/librte_eal/common/include \
-                          lib/librte_eal/common/include/generic \
-                          lib/librte_acl \
-                          lib/librte_bbdev \
-                          lib/librte_bitratestats \
-                          lib/librte_bpf \
-                          lib/librte_cfgfile \
-                          lib/librte_cmdline \
-                          lib/librte_compat \
-                          lib/librte_compressdev \
-                          lib/librte_cryptodev \
-                          lib/librte_distributor \
-                          lib/librte_efd \
-                          lib/librte_ethdev \
-                          lib/librte_eventdev \
-                          lib/librte_flow_classify \
-                          lib/librte_gro \
-                          lib/librte_gso \
-                          lib/librte_hash \
-                          lib/librte_ip_frag \
-                          lib/librte_jobstats \
-                          lib/librte_kni \
-                          lib/librte_kvargs \
-                          lib/librte_latencystats \
-                          lib/librte_lpm \
-                          lib/librte_mbuf \
-                          lib/librte_member \
-                          lib/librte_mempool \
-                          lib/librte_meter \
-                          lib/librte_metrics \
-                          lib/librte_net \
-                          lib/librte_pci \
-                          lib/librte_pdump \
-                          lib/librte_pipeline \
-                          lib/librte_port \
-                          lib/librte_power \
-                          lib/librte_rawdev \
-                          lib/librte_reorder \
-                          lib/librte_ring \
-                          lib/librte_sched \
-                          lib/librte_security \
-                          lib/librte_table \
-                          lib/librte_timer \
-                          lib/librte_vhost
-FILE_PATTERNS           = rte_*.h \
-                          cmdline.h
-PREDEFINED              = __DOXYGEN__ \
-			   VFIO_PRESENT \
-                          __attribute__(x)=
-
-OPTIMIZE_OUTPUT_FOR_C   = YES
-ENABLE_PREPROCESSING    = YES
-MACRO_EXPANSION         = YES
-EXPAND_ONLY_PREDEF      = YES
-EXTRACT_STATIC          = YES
-DISTRIBUTE_GROUP_DOC    = YES
-HIDE_UNDOC_MEMBERS      = YES
-HIDE_UNDOC_CLASSES      = YES
-HIDE_SCOPE_NAMES        = YES
-GENERATE_DEPRECATEDLIST = NO
-VERBATIM_HEADERS        = NO
-ALPHABETICAL_INDEX      = NO
-
-HTML_TIMESTAMP          = NO
-HTML_DYNAMIC_SECTIONS   = YES
-SEARCHENGINE            = NO
-SORT_MEMBER_DOCS        = NO
-SOURCE_BROWSER          = YES
-
-EXAMPLE_PATH            = examples
-EXAMPLE_PATTERNS        = *.c
-EXAMPLE_RECURSIVE       = YES
diff --git a/doc/api/doxy-api.conf.in b/doc/api/doxy-api.conf.in
new file mode 100644
index 0000000000..c3d8fdef18
--- /dev/null
+++ b/doc/api/doxy-api.conf.in
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2013-2017 6WIND S.A.
+
+PROJECT_NAME            = DPDK
+PROJECT_NUMBER          = @VERSION@
+INPUT                   = @TOPDIR@/doc/api/doxy-api-index.md \
+                          @TOPDIR@/drivers/crypto/scheduler \
+                          @TOPDIR@/drivers/mempool/dpaa2 \
+                          @TOPDIR@/drivers/net/bnxt \
+                          @TOPDIR@/drivers/net/bonding \
+                          @TOPDIR@/drivers/net/dpaa \
+                          @TOPDIR@/drivers/net/i40e \
+                          @TOPDIR@/drivers/net/ixgbe \
+                          @TOPDIR@/drivers/net/softnic \
+                          @TOPDIR@/drivers/raw/dpaa2_cmdif \
+                          @TOPDIR@/drivers/raw/dpaa2_qdma \
+                          @TOPDIR@/lib/librte_eal/common/include \
+                          @TOPDIR@/lib/librte_eal/common/include/generic \
+                          @TOPDIR@/lib/librte_acl \
+                          @TOPDIR@/lib/librte_bbdev \
+                          @TOPDIR@/lib/librte_bitratestats \
+                          @TOPDIR@/lib/librte_bpf \
+                          @TOPDIR@/lib/librte_cfgfile \
+                          @TOPDIR@/lib/librte_cmdline \
+                          @TOPDIR@/lib/librte_compat \
+                          @TOPDIR@/lib/librte_compressdev \
+                          @TOPDIR@/lib/librte_cryptodev \
+                          @TOPDIR@/lib/librte_distributor \
+                          @TOPDIR@/lib/librte_efd \
+                          @TOPDIR@/lib/librte_ethdev \
+                          @TOPDIR@/lib/librte_eventdev \
+                          @TOPDIR@/lib/librte_flow_classify \
+                          @TOPDIR@/lib/librte_gro \
+                          @TOPDIR@/lib/librte_gso \
+                          @TOPDIR@/lib/librte_hash \
+                          @TOPDIR@/lib/librte_ip_frag \
+                          @TOPDIR@/lib/librte_jobstats \
+                          @TOPDIR@/lib/librte_kni \
+                          @TOPDIR@/lib/librte_kvargs \
+                          @TOPDIR@/lib/librte_latencystats \
+                          @TOPDIR@/lib/librte_lpm \
+                          @TOPDIR@/lib/librte_mbuf \
+                          @TOPDIR@/lib/librte_member \
+                          @TOPDIR@/lib/librte_mempool \
+                          @TOPDIR@/lib/librte_meter \
+                          @TOPDIR@/lib/librte_metrics \
+                          @TOPDIR@/lib/librte_net \
+                          @TOPDIR@/lib/librte_pci \
+                          @TOPDIR@/lib/librte_pdump \
+                          @TOPDIR@/lib/librte_pipeline \
+                          @TOPDIR@/lib/librte_port \
+                          @TOPDIR@/lib/librte_power \
+                          @TOPDIR@/lib/librte_rawdev \
+                          @TOPDIR@/lib/librte_reorder \
+                          @TOPDIR@/lib/librte_ring \
+                          @TOPDIR@/lib/librte_sched \
+                          @TOPDIR@/lib/librte_security \
+                          @TOPDIR@/lib/librte_table \
+                          @TOPDIR@/lib/librte_timer \
+                          @TOPDIR@/lib/librte_vhost
+INPUT                   += @API_EXAMPLES@
+FILE_PATTERNS           = rte_*.h \
+                          cmdline.h
+PREDEFINED              = __DOXYGEN__ \
+			   VFIO_PRESENT \
+                          __attribute__(x)=
+
+OPTIMIZE_OUTPUT_FOR_C   = YES
+ENABLE_PREPROCESSING    = YES
+MACRO_EXPANSION         = YES
+EXPAND_ONLY_PREDEF      = YES
+EXTRACT_STATIC          = YES
+DISTRIBUTE_GROUP_DOC    = YES
+HIDE_UNDOC_MEMBERS      = YES
+HIDE_UNDOC_CLASSES      = YES
+HIDE_SCOPE_NAMES        = YES
+GENERATE_DEPRECATEDLIST = NO
+VERBATIM_HEADERS        = NO
+ALPHABETICAL_INDEX      = NO
+
+HTML_TIMESTAMP          = NO
+HTML_DYNAMIC_SECTIONS   = YES
+SEARCHENGINE            = NO
+SORT_MEMBER_DOCS        = NO
+SOURCE_BROWSER          = YES
+
+EXAMPLE_PATH            = @TOPDIR@/examples
+EXAMPLE_PATTERNS        = *.c
+EXAMPLE_RECURSIVE       = YES
+
+OUTPUT_DIRECTORY        = @OUTPUT@
+STRIP_FROM_PATH         = @STRIP_FROM_PATH@
+GENERATE_HTML           = YES
+HTML_OUTPUT             = @HTML_OUTPUT@
+GENERATE_LATEX          = NO
+GENERATE_MAN            = NO
diff --git a/mk/rte.sdkdoc.mk b/mk/rte.sdkdoc.mk
index d023b720fe..c44db6447a 100644
--- a/mk/rte.sdkdoc.mk
+++ b/mk/rte.sdkdoc.mk
@@ -43,15 +43,13 @@ clean: api-html-clean guides-html-clean guides-pdf-clean guides-man-clean
 api-html: $(API_EXAMPLES)
 	@echo 'doxygen for API...'
 	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
-	$(Q)(cat $(RTE_SDK)/doc/api/doxy-api.conf     && \
-	    printf 'PROJECT_NUMBER = '                && \
-	                     $(MAKE) -rRs showversion && \
-	    echo INPUT           += $(API_EXAMPLES)   && \
-	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
-	    echo HTML_OUTPUT      = html/api          && \
-	    echo GENERATE_HTML    = YES               && \
-	    echo GENERATE_LATEX   = NO                && \
-	    echo GENERATE_MAN     = NO                )| \
+	$(Q)(sed -e "s|@VERSION@|`$(MAKE) -rRs showversion`|" \
+	         -e "s|@API_EXAMPLES@|$(API_EXAMPLES)|"       \
+	         -e "s|@OUTPUT@|$(RTE_OUTPUT)/doc|"           \
+	         -e "s|@HTML_OUTPUT@|html/api|"               \
+	         -e "s|@TOPDIR@|./|g"                         \
+	         -e "s|@STRIP_FROM_PATH@|./|g"                \
+	         $(RTE_SDK)/doc/api/doxy-api.conf.in)|        \
 	    doxygen -
 	$(Q)$(RTE_SDK)/doc/api/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
 
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v5 3/4] build: use same version as make showversion in Meson
  2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
@ 2018-09-11 20:42   ` Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson Luca Boccassi
  2 siblings, 0 replies; 39+ messages in thread
From: Luca Boccassi @ 2018-09-11 20:42 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

make showversion will print 18.11.0-rc0 but Meson sets 18.11-rc0,
causing among other things a difference in the generated documentation.

Fixes: 76b9d9de5c7d ("version: 18.11-rc0")

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v3: add acked-by

 meson.build | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/meson.build b/meson.build
index 84af32ecef..9999e8640a 100644
--- a/meson.build
+++ b/meson.build
@@ -2,7 +2,7 @@
 # Copyright(c) 2017 Intel Corporation
 
 project('DPDK', 'C',
-	version: '18.11-rc0',
+	version: '18.11.0-rc0',
 	license: 'BSD',
 	default_options: ['buildtype=release', 'default_library=static'],
 	meson_version: '>= 0.41'
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson
  2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 3/4] build: use same version as make showversion in Meson Luca Boccassi
@ 2018-09-11 20:42   ` Luca Boccassi
  2018-09-18 13:48     ` Thomas Monjalon
  2 siblings, 1 reply; 39+ messages in thread
From: Luca Boccassi @ 2018-09-11 20:42 UTC (permalink / raw)
  To: dev; +Cc: bruce.richardson, john.mcnamara, marko.kovacevic, thomas

Signed-off-by: Luca Boccassi <bluca@debian.org>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
---
v2: made doxygen dependency optional, skip doxygen build when not found
v3: made doxygen dependency mandatory if enable_docs is true, add
    alternative doc target that prints "doxygen not found" when doxygen
    is not found and enable_docs is false (default)
v4: add acked-by
v5: change install directory to $PREFIX/share/doc/dpdk to match legacy
    makefiles

 doc/api/generate_doxygen.sh | 10 +++++++
 doc/api/meson.build         | 56 +++++++++++++++++++++++++++++++++++++
 doc/build-sdk-meson.txt     |  2 ++
 doc/meson.build             |  4 +++
 meson.build                 |  3 ++
 meson_options.txt           |  2 ++
 6 files changed, 77 insertions(+)
 create mode 100755 doc/api/generate_doxygen.sh
 create mode 100644 doc/api/meson.build
 create mode 100644 doc/meson.build

diff --git a/doc/api/generate_doxygen.sh b/doc/api/generate_doxygen.sh
new file mode 100755
index 0000000000..ab57660958
--- /dev/null
+++ b/doc/api/generate_doxygen.sh
@@ -0,0 +1,10 @@
+#! /bin/sh -e
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright 2018 Luca Boccassi <bluca@debian.org>
+
+DOXYCONF=$1
+OUTDIR=$2
+SCRIPTCSS=$3
+
+doxygen "${DOXYCONF}"
+"${SCRIPTCSS}" "${OUTDIR}"/doxygen.css
diff --git a/doc/api/meson.build b/doc/api/meson.build
new file mode 100644
index 0000000000..13fcbb8cd7
--- /dev/null
+++ b/doc/api/meson.build
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+doxygen = find_program('doxygen', required: get_option('enable_docs'))
+
+if doxygen.found()
+	# due to the CSS customisation script, which needs to run on a file that
+	# is in a subdirectory that is created at build time and thus it cannot
+	# be an individual custom_target, we need to wrap the doxygen call in a
+	# script to run the CSS modification afterwards
+	generate_doxygen = find_program('generate_doxygen.sh')
+	generate_examples = find_program('generate_examples.sh')
+	generate_css = find_program('doxy-html-custom.sh')
+
+	inputdir = join_paths(meson.source_root(), 'examples')
+	htmldir = join_paths('share', 'doc', 'dpdk')
+
+	# due to the following bug: https://github.com/mesonbuild/meson/issues/4107
+	# if install is set to true it will override build_by_default and it will
+	# cause the target to always be built. If install were to be always set to
+	# false it would be impossible to install the docs.
+	# So use a configure option for now.
+	example = custom_target('examples.dox',
+		input: inputdir,
+		output: 'examples.dox',
+		command: [generate_examples, '@INPUT@', '@OUTPUT@'],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	cdata = configuration_data()
+	cdata.set('VERSION', meson.project_version())
+	cdata.set('API_EXAMPLES', join_paths(meson.build_root(), 'doc', 'api', 'examples.dox'))
+	cdata.set('OUTPUT', join_paths(meson.build_root(), 'doc', 'api'))
+	cdata.set('HTML_OUTPUT', 'api')
+	cdata.set('TOPDIR', meson.source_root())
+	cdata.set('STRIP_FROM_PATH', meson.source_root())
+
+	doxy_conf = configure_file(input: 'doxy-api.conf.in',
+		output: 'doxy-api.conf',
+		configuration: cdata,
+		install: false)
+
+	doxy_build = custom_target('doxygen',
+		depends: example,
+		input: doxy_conf,
+		output: 'api',
+		command: [generate_doxygen, '@INPUT@', '@OUTPUT@', generate_css],
+		install: get_option('enable_docs'),
+		install_dir: htmldir,
+		build_by_default: false)
+
+	run_target('doc', command: 'true', depends: doxy_build)
+else
+	run_target('doc', command: ['echo', 'doxygen', 'not', 'found'])
+endif
diff --git a/doc/build-sdk-meson.txt b/doc/build-sdk-meson.txt
index 9618e759ea..508e2cb642 100644
--- a/doc/build-sdk-meson.txt
+++ b/doc/build-sdk-meson.txt
@@ -85,6 +85,8 @@ Project-specific options are passed used -Doption=value::
 
 	meson -Dmax_lcores=8 smallbuild  # scale build for smaller systems
 
+	meson -Denable_docs=true fullbuild  # build and install docs
+
 Examples of setting the same options using meson configure::
 
 	meson configure -Dwerror=true
diff --git a/doc/meson.build b/doc/meson.build
new file mode 100644
index 0000000000..afca2e7133
--- /dev/null
+++ b/doc/meson.build
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright(c) 2018 Luca Boccassi <bluca@debian.org>
+
+subdir('api')
diff --git a/meson.build b/meson.build
index 9999e8640a..09506ec48c 100644
--- a/meson.build
+++ b/meson.build
@@ -34,6 +34,9 @@ subdir('usertools')
 subdir('app')
 subdir('test')
 
+# build docs
+subdir('doc')
+
 # build any examples explicitly requested - useful for developers
 if get_option('examples') != ''
 	subdir('examples')
diff --git a/meson_options.txt b/meson_options.txt
index f20887212a..d38ba56e29 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -2,6 +2,8 @@ option('allow_invalid_socket_id', type: 'boolean', value: false,
 	description: 'allow out-of-range NUMA socket id\'s for platforms that don\'t report the value correctly')
 option('enable_kmods', type: 'boolean', value: true,
 	description: 'build kernel modules')
+option('enable_docs', type: 'boolean', value: false,
+	description: 'build documentation')
 option('examples', type: 'string', value: '',
 	description: 'Comma-separated list of examples to build by default')
 option('include_subdir_arch', type: 'string', value: '',
-- 
2.18.0

^ permalink raw reply	[flat|nested] 39+ messages in thread

* Re: [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson
  2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson Luca Boccassi
@ 2018-09-18 13:48     ` Thomas Monjalon
  0 siblings, 0 replies; 39+ messages in thread
From: Thomas Monjalon @ 2018-09-18 13:48 UTC (permalink / raw)
  To: Luca Boccassi; +Cc: dev, bruce.richardson, john.mcnamara, marko.kovacevic

11/09/2018 22:42, Luca Boccassi:
> Signed-off-by: Luca Boccassi <bluca@debian.org>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>

Series applied, thanks

^ permalink raw reply	[flat|nested] 39+ messages in thread

end of thread, other threads:[~2018-09-18 13:48 UTC | newest]

Thread overview: 39+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-08-31 18:20 [dpdk-dev] [PATCH 0/4] Meson: build Doxygen documentation Luca Boccassi
2018-08-31 18:20 ` [dpdk-dev] [PATCH 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-03  0:54   ` Thomas Monjalon
2018-09-03  9:07     ` Luca Boccassi
2018-09-07 16:13       ` Bruce Richardson
2018-09-07 16:56         ` Luca Boccassi
2018-08-31 18:20 ` [dpdk-dev] [PATCH 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-03  1:03   ` Thomas Monjalon
2018-09-03  9:08     ` Luca Boccassi
2018-08-31 18:20 ` [dpdk-dev] [PATCH 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-03  1:04   ` Thomas Monjalon
2018-08-31 18:20 ` [dpdk-dev] [PATCH 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-03  1:09   ` Thomas Monjalon
2018-09-03  9:34     ` Luca Boccassi
2018-09-07 16:31   ` Bruce Richardson
2018-09-07 16:56     ` Luca Boccassi
2018-09-07 16:55 ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-07 16:55   ` [dpdk-dev] [PATCH v2 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-10 15:47     ` Bruce Richardson
2018-09-10 16:15       ` Luca Boccassi
2018-09-10 15:49   ` [dpdk-dev] [PATCH v2 1/4] mk: use script to generate examples.dox Bruce Richardson
2018-09-10 16:13   ` [dpdk-dev] [PATCH v3 " Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 16:13     ` [dpdk-dev] [PATCH v3 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-10 17:30       ` Bruce Richardson
2018-09-10 17:32         ` Bruce Richardson
2018-09-10 17:35         ` Luca Boccassi
2018-09-10 20:09 ` [dpdk-dev] [PATCH v4 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-10 20:09   ` [dpdk-dev] [PATCH v4 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-10 20:10   ` [dpdk-dev] [PATCH v4 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-11 20:42 ` [dpdk-dev] [PATCH v5 1/4] mk: use script to generate examples.dox Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 2/4] mk: use templated doxygen config, modified on the fly Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 3/4] build: use same version as make showversion in Meson Luca Boccassi
2018-09-11 20:42   ` [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson Luca Boccassi
2018-09-18 13:48     ` Thomas Monjalon

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).