From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 90A9F42C3E; Tue, 6 Jun 2023 12:55:07 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5F67240A84; Tue, 6 Jun 2023 12:55:07 +0200 (CEST) Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by mails.dpdk.org (Postfix) with ESMTP id F2D3C40223 for ; Tue, 6 Jun 2023 12:55:05 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1686048906; x=1717584906; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=NwjRYdVUwg/KrNQcPAVzd20ORJdQluX1V9g1EFUJl/s=; b=nz2NYV7Tve518/T422Y/6Ds+DIE7VqwEn0yxU6hV+CaukPVr+SfPIY12 z+csxzSwVCNyYzhnP8tqXjuNoRdD+9z4CCoNTsLITJ9YV5BdBGJsxsWUY vG4Gp0kHJWqYvigHnhZQn/0mFkzoevGbY699laM6x5Di/75d+cld3Gml9 OVYEYhdpufm4eQQrMc1M2uuh14SgMq1ip6hLgowFdEa9VZirJw3VgmHDk aJDl3YyaztEnYVAtowqvEgosDwnUA+0/4TxTEU+5BQNrS8YowwbAk1GdJ 4fCEv5wvoTQic0eQHoj/6xvTqXQttgTuuGuEVE6bdkG6Xs/qXiBjmnoJr w==; X-IronPort-AV: E=McAfee;i="6600,9927,10732"; a="346231378" X-IronPort-AV: E=Sophos;i="6.00,221,1681196400"; d="scan'208";a="346231378" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 06 Jun 2023 03:55:04 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10732"; a="883293821" X-IronPort-AV: E=Sophos;i="6.00,221,1681196400"; d="scan'208";a="883293821" Received: from fmsmsx601.amr.corp.intel.com ([10.18.126.81]) by orsmga005.jf.intel.com with ESMTP; 06 Jun 2023 03:55:04 -0700 Received: from fmsmsx610.amr.corp.intel.com (10.18.126.90) by fmsmsx601.amr.corp.intel.com (10.18.126.81) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.23; Tue, 6 Jun 2023 03:55:03 -0700 Received: from fmsedg602.ED.cps.intel.com (10.1.192.136) by fmsmsx610.amr.corp.intel.com (10.18.126.90) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.23 via Frontend Transport; Tue, 6 Jun 2023 03:55:03 -0700 Received: from NAM11-DM6-obe.outbound.protection.outlook.com (104.47.57.170) by edgegateway.intel.com (192.55.55.71) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.23; Tue, 6 Jun 2023 03:55:02 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=IgqALk2qIr8Q9I7/WCvv26POO3Qw5Owx6ZFowtCQTceAj9kd73fRsi2BOdW2ta2xXuLeqSkiqcLupnUsFlXfCVWRn7BYt0KmQUxkud7KN4C9oNlxqsui8M++au3GJgz8IxDGd373dtDg4IxedLGTNInLqBqrR3e+BS4kTOHksGd8i2YMWs4YgSBYrlOjaWtvuVTf474I7bD/i5uJkoVD3gIDdgFA4npBJIry9Cc1ylSOziiu4WriuMuWOIXJSuDExqFTrmdWZRPQch6flgaoyF9lDjmY5juEIKSzkP7s4/1ytA0BFzCKU/CPwAGcCr/c9l6hnbB1KfUyEgd00n+Jdg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=1y4h+y44wa9T50uFVBKnEdd7X9JqAL4m3UysZAt44ww=; b=L0GME4NtoZ+3YEefFgOrG6pilDZaFM8pQIzkY/JeJaMmroCUXiN6lMn4bUHqDIZi9fDP5Ht/o0MLc9cf6cJdaPvUuB98xJuUNqlMvt3PGG2ZDbm9Uj5hVVhy+ovlYTGEcr0kLC4D+wpaUtkcAVPHAxevzMlXpsgV/S30NpcKTK97ss9/1Yr8jEuCId/feb1TazYYc6lXb5zKL4UpX8sD44Y8Jk/9nUSr64WLTLIqSZeL6dMiI9vYjuxZrU7C6IVrEwR17eBIzLAsn9C3cJ8x7ez+sBsFfGbOpLtd2ZfhQ6xujLxorFfINsaxi5/UARZyuTWaJzA2s2c22PiGmCeNEA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=intel.com; Received: from DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) by PH7PR11MB6954.namprd11.prod.outlook.com (2603:10b6:510:205::8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6455.32; Tue, 6 Jun 2023 10:55:01 +0000 Received: from DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::b8f3:958:d2c5:2232]) by DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::b8f3:958:d2c5:2232%7]) with mapi id 15.20.6455.030; Tue, 6 Jun 2023 10:55:00 +0000 Date: Tue, 6 Jun 2023 11:54:54 +0100 From: Bruce Richardson To: Jerin Jacob CC: Subject: Re: [PATCH] doc: build manpages as well as html output Message-ID: References: <20230601153801.118616-1-bruce.richardson@intel.com> Content-Type: text/plain; charset="utf-8" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: X-ClientProxiedBy: LO2P265CA0117.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:c::33) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|PH7PR11MB6954:EE_ X-MS-Office365-Filtering-Correlation-Id: cfa700d3-8a28-46bd-4c6a-08db667c7964 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: SOHAF0TveHmUKk7+uzxcEIkrhrhv5ngsk6yR50nYCH1BNS4A3vjK28LGb1IkSmwfIPXbR0OeBduLeHAhPMnpNDzsglIhYoIcuDPmQ3SolBP6ZbdlB9NYY4Ro98ATgd0YU4KdZSVinyUHxo08Zr1Y8/uXDYcoFMte65nCnprHSXPZMSZtO5VGgVTk3mtL4D7qphLrE0GgfEIdc51MW2gBt8fGgw1orGgAAoh35l2aaDhoL5MdC5qX+rNNZrmIj7tWzYhaHic7HfuR6Y8s5x5HuxzI0ty2u4foHYyUsDqhgzhZxCcN06Tmw/TgnGDZ2vpJrK1To8YxhnYlxFFbgau8fRgnvKnfVNyrnQFwVpZeYGS5SF0ca2e2IKSFHxSpU6zAuxEYbsS7/p24nQjBVvf0oVEUq+0+fTdEtVA5+5s7MbDhtYYyVhbBmduwGoUYP794tikirjeSKqTGpTT28m9Hq5Z0N8jtVy7Gbb1LUAorxR3bHFf3t+yMPUdBF+f1P/sGEYgA6IsfdrRNSxWoQYr7nxZ5F9IEHyXOVvmIQoSIGFrUOuisJD+L+KrXT866Cnt9 X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DS0PR11MB7309.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230028)(39860400002)(366004)(376002)(136003)(346002)(396003)(451199021)(83380400001)(44832011)(4326008)(478600001)(82960400001)(8936002)(8676002)(316002)(66556008)(66476007)(66946007)(5660300002)(38100700002)(6916009)(86362001)(41300700001)(6666004)(6486002)(2906002)(53546011)(186003)(6512007)(26005)(6506007); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?ay9hTlk5ak12WUFCcEpyWlB6ZDZTWFFkVmUvdzZvNkpSU05XQitCS3FhcU4x?= =?utf-8?B?emF0eGFQTW1tTU5pdkVua25ycE1KNTF0dTZPWGMwNEl6TmE0cmVHVjdtbFlV?= =?utf-8?B?SVhYZmVFaUZvb3JhT0lRVVI2QmZEc3FFbkhxdzliaGY5eHAvY1NLbnNyS2pz?= =?utf-8?B?SXdmeUlQUjRjUmhvUkIzUnphOVpmL3B3d2I4TEZyVk8vam9UajRFMkt5Rm1l?= =?utf-8?B?Ly9xMmhyek5XWG5qRDZwN0kvZmZhVk1QVlJvbVR4Z3NUdG1xaC96NndtTFR4?= =?utf-8?B?cGVFdmpTc1IzTlFabFkwemc4d2RrWkF2cjVWb2puQjVnZmx4RTVqWnV4S2dW?= =?utf-8?B?anJRbWVXN3l4c0VmTW9pTWh5QjVaa3RjbHBvNFdYa29JbjZ3TEtDL3dNbUJk?= =?utf-8?B?VGt2WTBqQUNBQlV0a3kxTDVlMFdYZUNuQmFNZkhhY3IxQ09saEY2Z2VQUEUz?= =?utf-8?B?T0pCOGhnV1JQQ09KbmN1Ukx2RkY3ek94c3M5QVQ5R1d0SGpra1ZRZHpxMVdt?= =?utf-8?B?VFlnQzdBU2JybzJ5bjVBQXYzOUNMTW44NXc4UUFPRjFtUG9tOW5QQ3NETUIy?= =?utf-8?B?bkJmb0JYam5pQ2h1WXJhemFJbnI5TjdDcU5lRzNSQTlLdmRMempzSnpvQk9j?= =?utf-8?B?TlZTbkw2TXBkRTJOZ0YyeDNGYm5YNHVRb3NzakxleUJ1TWxEWDJTenk4ZXBv?= =?utf-8?B?L0FqQ1RaYXcvdmgvbW42aTNJUVZlZlluRzNpSStnS1B5NmZ6cGNNZEh0d2I5?= =?utf-8?B?Qm1zMjVqUlJ4a0JJZFhhRHA3akVoL2FFaXhOY1BaRUxGTUgzUXpTVmtqUS9D?= =?utf-8?B?VlZNOHhkQWFLOEd3OUk0WWtMek9aYXJFLzRpMWZPU2lzSlJYb1lQdzlkaUsx?= =?utf-8?B?SEhiQkdMRUxVbDNtc3FIODQ3dVBpbFB1bng1L2EyRU45MHVZaDRrakRldmJj?= =?utf-8?B?UjRpclVkNXZIUitiMHpBMmFaZ24vMk1XQnhsQnk0dzFJQ1NZenBOaExSbHRT?= =?utf-8?B?aFkyb25Lci9pcFlHRUNSZXBpbjIxcTljdGs5SUZmaXVqQ2Zlek1HRUJRWklX?= =?utf-8?B?amNMbnpQVlptQ0JGMHY3Tk1UK3VNWkNtYjY5dFcwWWNoWjNrMlRUSVV6TjRQ?= =?utf-8?B?ekVJdUJla1BTTWp6ak9EWHE1OEZna3BvVmN2RjlVb0toS0IzbFJ0SGd2dm1x?= =?utf-8?B?R0h3YUNUMzVvWFgxL2hFTGMrK1BzV2VZM2YwTmYvTko2RWRFTUIvSEFTUHAx?= =?utf-8?B?a00xeEJUWnJKWlg1TGVZODJSeS9TcFdIKzhKbDBiczB2ankwN2duT3RwYjM3?= =?utf-8?B?dS84T05EVG53T0sxZW1SYTRRRDY3a3R2ZFlSSXpVaXBEMFpXalRKdE1IL3FN?= =?utf-8?B?VDlIVDVzZy9yWEhnVi91TkdKMTZjMm9iOHZsdjlxYWNpVzMvaHNvUFJnS1lt?= =?utf-8?B?MU1GK0RwaENLTmpvanYzK2hoOWtGK1I4UmFTUUNaN3M5M0dVNEFsUWhTMFk3?= =?utf-8?B?VmUzcEhIbmVLK1FucW5kYlVCUkhQb01GZVpRM2M0RVZIa2VKKzBvQlhQT2hs?= =?utf-8?B?K2J2NEZncnBsRlVRVDgxeVM0dFoxc2ZybTRENFdrM1NrUWJSc0c1dXgzVGdZ?= =?utf-8?B?OGQ4OGdkbXNHZjVXNjBVU3JWWVFtTDlTaFMwZXBZVklJRVE1QTFLRFZoaDZE?= =?utf-8?B?SlVYRXk4MmswMTdSMGxMbDNOSEFDQXVvTUVvaHJXeUdEVEhyUk1TRzUremgr?= =?utf-8?B?WVFRK1JnT09STVFuWGVXbWgwUWdyUEk1dXNyaTVlWllpY1RXd3BuNEJvRUJ1?= =?utf-8?B?Uzc4TVFuMXZWQk1sbHAyQWFBVnArcDZQS2FXNUtKZE8ybEh6dG1xN0Z4N3Rh?= =?utf-8?B?cjhnY3lsM3Y3S3BVR2xQNXduTjRzOWVuOWptbElBNUtQeUNoVk5HNEdKaks2?= =?utf-8?B?eDN4S08zNGpyRytzU0NPajVPVlZrVlBSTWRIcUZZREVOQWdWNWpyQWJ1V3BZ?= =?utf-8?B?Slp1aXJSNFQ3ZzR1QW1VQlk4dGlPZkdHdGRVYnI3MklsYXVHQzRsaWNvZmI2?= =?utf-8?B?SkdIejA2aVpWVmFvQjdaQXdIQWhINWFjYk5YdGtVZWh3Zm1WM204RmE2Z2wr?= =?utf-8?B?c3NvMFpuR09xbnArU2poYzRVVnliQTFUNk9xdHZyUmJPT2diT0xRRmQwU1pV?= =?utf-8?B?ZFE9PQ==?= X-MS-Exchange-CrossTenant-Network-Message-Id: cfa700d3-8a28-46bd-4c6a-08db667c7964 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 06 Jun 2023 10:55:00.3861 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: 8W7XKg7uES6Rz1WQvPf3D0zb6xeugeC0NvaQPfdekcxUBSYavJxzxkDzlH3k1LJ4R1HpbLnmOIZk2v6J88/yqRwV8XHm12fQK6Hwl41JXzs= X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH7PR11MB6954 X-OriginatorOrg: intel.com X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On Tue, Jun 06, 2023 at 04:19:27PM +0530, Jerin Jacob wrote: > On Tue, Jun 6, 2023 at 3:49 PM Bruce Richardson > wrote: > > > > On Tue, Jun 06, 2023 at 03:16:27PM +0530, Jerin Jacob wrote: > > > On Tue, Jun 6, 2023 at 2:49 PM Bruce Richardson > > > wrote: > > > > > > > > On Mon, Jun 05, 2023 at 10:50:48AM +0530, Jerin Jacob wrote: > > > > > On Thu, Jun 1, 2023 at 9:08 PM Bruce Richardson > > > > > wrote: > > > > > > > > > > > > Doxygen can produce manpage output as well as html output for the DPDK > > > > > > APIs. However, we need to do this as a separate task as the manpage > > > > > > output needs to be placed in a different location post-install to the > > > > > > html output (/usr/local/share/man vs /usr/local/share/doc/). > > > > > > > > > > > > Changes required are: > > > > > > * Add configurable options for manpage output and html output to the > > > > > > doxygen config template. (Remove option for html output path as it's > > > > > > always "html") > > > > > > * Modify API meson.build file to configure two separate doxygen config > > > > > > files, for HTML and manpages respectively. > > > > > > * Change doxygen wrapper script to have separate output log files for > > > > > > the manpage and HTML jobs, to avoid conflicts > > > > > > * Add "custom_targets" to meson.build file to build the HTML pages and > > > > > > the manpages, with individual install locations for each. > > > > > > * Where supported by meson version, call "mandb" post-install to update > > > > > > the man database to ensure the new manpages can be found. > > > > > > > > > > > > Signed-off-by: Bruce Richardson > > > > > > > > > > > + > > > > > > +mandb = find_program('mandb', required: false) > > > > > > +if mandb.found() and get_option('enable_docs') and meson.version().version_compare('>=0.55.0') > > > > > > + meson.add_install_script(mandb) > > > > > > > > > > It does not look like just executing mandb it is adding these man > > > > > pages to database > > > > > > > > > > log: > > > > > Running custom install script '/usr/bin/mandb' > > > > > Purging old database entries in /home/jerin/.local/man... > > > > > Processing manual pages under /home/jerin/.local/man... > > > > > Checking for stray cats under /home/jerin/.local/man... > > > > > Processing manual pages under /home/jerin/.local/man/cat1... > > > > > Purging old database entries in /home/jerin/.local/share/man... > > > > > Processing manual pages under /home/jerin/.local/share/man... > > > > > Checking for stray cats under /home/jerin/.local/share/man... > > > > > Processing manual pages under /home/jerin/.local/share/man/cat1... > > > > > 0 man subdirectories contained newer manual pages. > > > > > 0 manual pages were added. > > > > > 0 stray cats were added. > > > > > 0 old database entries were purged. > > > > > > > > > > [main][dpdk.org] $ man rte_flow_create > > > > > No manual entry for rte_flow_create > > > > > > > > > > # Following works by providing the path i.e man pages created properly > > > > > only db update is missing > > > > > man --manpath=/tmp/i/usr/local/share/man/ rte_flow_create > > > > > > > > > Yes, that is correct. > > > > > > > > If you install to a non-standard location, then yes you need to update > > > > manpath yourself. However, in case you install to a "standard" location, > > > > then running mandb will update the database for you. I believe this is the > > > > behaviour we should have. I view it as the same as installing binaries in a > > > > standard vs non-standard path - if the binaries are placed in a standard > > > > location then they are found automatically, but if installed in a custom > > > > location, then the user is responsible for ensuring all paths are correct. > > > > > > OK. Then I think, we can move "meson.add_install_script(mandb)" > > > invocation under !DESTDIR not provided. > > > As if DESTDIR is provided then there is no use for mandb. > > > > > That would mean adding a new build script to run mandb, since: > > * meson doesn't directly support getting environment variables > > * DESTDIR may only be set at install time rather than at configuration > > time, so we'll always need to set up the build script > > > > Furthermore, I'd point out that DESTDIR is not going to avoid unnecessary > > runs of mandb, since using a special "prefix" setting would also cause the > > manpages to not be found. > > > > Overall, I'd view the complexity of avoiding the mandb call not to be > > worth it, since calling mandb is largely harmless - bar the time taken to > > run it. However, if you feel strongly it should be skipped when installing > > with DESTDIR > > No strong option. OK to skip DESTDIR check. > > >, I'll spin a v2 with the wrapper script added. Let me know > > what you think? > > I think, it is good to update doc/guides/contributing/documentation.rst > on how to use the man page(i.e use with --manpage) > Ok, will spin a v2.