From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-f65.google.com (mail-wr1-f65.google.com [209.85.221.65]) by dpdk.org (Postfix) with ESMTP id B7A934D27 for ; Tue, 11 Sep 2018 22:42:47 +0200 (CEST) Received: by mail-wr1-f65.google.com with SMTP id g33-v6so27460373wrd.1 for ; Tue, 11 Sep 2018 13:42:47 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=Q7iv5ljMvI9xCPJFp3ZfQ/0wuFwbRCllcEo/b3iQMkA=; b=XwnLEo9MD6Z+TeWly2N3pz1Y/lAwq4fBC6Be+R5ZJR3yq6BcNZe4FWYPl2Axrka12U UhtxYiq8JolaFVJkJGL7JDiIlaLbvsS1tXA2VYUhOdsutwQfJeSGXPpRTtZv6GQMZ13k WYUTnO/zcwYYnK0Tub95qtt6fypPuxnSBLtBNMZn9vOGUwJxNlHhnIHq0nBZOuQooTvS uxrhnA9IZE9f4/nSf6occP9G/Cht6J+vY8m8QbhmG0d2qOheqj07LN4O03zfAbn2OHr/ 5C1EWydxOc7B96uQ6Mue6D1foMi5vZQME6jy1p6AY/+IVryYbT0YWWb6tMOYgVCOIYm3 DKvQ== X-Gm-Message-State: APzg51DXZUPagMgqjc6RGIjsjE8yT/gZb+cipZgLShhUxvFhIbP7/OiQ X2fL4gOf7qJHI42u6BkoHVZjyTuaLbw= X-Google-Smtp-Source: ANB0VdZO59Ppyrlo9IX9b7wBiJ0v1H4TeTMg98rAn3KuOKeP535G0RlLagIyb4yzZHJLzraT9lK3HA== X-Received: by 2002:a5d:4b90:: with SMTP id b16-v6mr20851417wrt.168.1536698566983; Tue, 11 Sep 2018 13:42:46 -0700 (PDT) Received: from localhost ([2a01:4b00:f419:6f00:8361:8946:ba2b:d556]) by smtp.gmail.com with ESMTPSA id f17-v6sm23949443wrs.1.2018.09.11.13.42.45 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 11 Sep 2018 13:42:45 -0700 (PDT) From: Luca Boccassi To: dev@dpdk.org Cc: bruce.richardson@intel.com, john.mcnamara@intel.com, marko.kovacevic@intel.com, thomas@monjalon.net Date: Tue, 11 Sep 2018 21:42:36 +0100 Message-Id: <20180911204236.21858-4-bluca@debian.org> X-Mailer: git-send-email 2.18.0 In-Reply-To: <20180911204236.21858-1-bluca@debian.org> References: <20180831182055.30772-1-bluca@debian.org> <20180911204236.21858-1-bluca@debian.org> Subject: [dpdk-dev] [PATCH v5 4/4] build: generate API documentation with Meson X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 11 Sep 2018 20:42:48 -0000 Signed-off-by: Luca Boccassi Acked-by: Bruce Richardson --- 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 + +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 + +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 + +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