From patchwork Thu Apr 29 05:47:32 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Grant Seltzer Richman X-Patchwork-Id: 12231981 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-14.7 required=3.0 tests=BAYES_00,DATE_IN_PAST_12_24, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4D926C433ED for ; Thu, 29 Apr 2021 21:41:05 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 28B0C61469 for ; Thu, 29 Apr 2021 21:41:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234837AbhD2Vlv (ORCPT ); Thu, 29 Apr 2021 17:41:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51752 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S237191AbhD2Vlu (ORCPT ); Thu, 29 Apr 2021 17:41:50 -0400 Received: from mail-qk1-x733.google.com (mail-qk1-x733.google.com [IPv6:2607:f8b0:4864:20::733]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C2371C06138B for ; Thu, 29 Apr 2021 14:41:01 -0700 (PDT) Received: by mail-qk1-x733.google.com with SMTP id v23so16752033qkj.13 for ; Thu, 29 Apr 2021 14:41:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Bh3Tiv9fi414wqxwp/rVd3VoQ2MHmty+9gktKiecaBk=; b=FC+xn6iG4nXGDv0NBTzvGTIhiOb1XXZhanFyUVZx9uGJP6BqVx33iLwEbFEjlMclXf ATl9FPvh/zmasN/hhBLL4dnKh9KKJZKKv4205cOkmvXsSzAAJIY1RvPU1WfLfogIRFVl +7nZv9cm5HvacMNMlxX9ciaST2B59bue8zMGYn4Pbt5pwYQ2P/oyL89TduLaStnHusXr /o11I23VxefXqeei+WBF8fNPBekwOfNqiLKwnVRrYSIm+pKZxxYtMjZf3eK5Kv20BLM3 pX29L9lO7G9znX2dDFpLOtQ3fT3f3L7LBvqOfzQzNhLhwP4hb0k11VCTLe0b49OB8CZ0 BWuA== 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:mime-version:content-transfer-encoding; bh=Bh3Tiv9fi414wqxwp/rVd3VoQ2MHmty+9gktKiecaBk=; b=O1+7XuRt9t6hNWFf21k6DOkkkohnxqj1xfp1IY29xfgoSCwoVP+OqYP21zm8HTkFQb JhSMy5l+73xsx4O8gYvkZN3iSNDZwnyOjqs02kpBY8W9I7ciYwNMPIIgSAQpb8jEnMXf rtsNm1feY96W0VovNXSmYvbbaL3Dee6AKS50dKMZIZ2mVXRIOFiZ8fX6m8N+EhGT/VAf wiTKQzvH4XbQU2/ZdKIy7LIkU3P9jRDHRGL5oqE4TJSUZ3xfyDHv0Xqp3KOo2ABkthPo h/PTHlXSbmWiC4I7ds5tDRdlaKpcgB7yu3EC41IlfD9MBO84e9OlXlF9XQmvQT2PWaSc GZ9g== X-Gm-Message-State: AOAM531l5sW87RcOIB/nURaVlvBQm9pGfPCdSvzL+XAiFH9rnYnLdTBv EtQqzZSf6AlPC3fm3hPX9Pw= X-Google-Smtp-Source: ABdhPJzqt9sxhsYLQjSjxLY7rPI7f/Z4rSJjaj5ln6b5mZ6YnwENObrdiaKym4NHzGzukRTqSlYlcw== X-Received: by 2002:a37:9b02:: with SMTP id d2mr1926612qke.207.1619732460961; Thu, 29 Apr 2021 14:41:00 -0700 (PDT) Received: from localhost.localdomain (pool-100-33-2-40.nycmny.fios.verizon.net. [100.33.2.40]) by smtp.gmail.com with ESMTPSA id m16sm2993869qkm.100.2021.04.29.14.41.00 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Apr 2021 14:41:00 -0700 (PDT) From: grantseltzer To: andrii@kernel.org, daniel@iogearbox.net Cc: grantseltzer@gmail.com, bpf@vger.kernel.org Subject: [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files Date: Thu, 29 Apr 2021 05:47:32 +0000 Message-Id: <20210429054734.53264-2-grantseltzer@gmail.com> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20210429054734.53264-1-grantseltzer@gmail.com> References: <20210429054734.53264-1-grantseltzer@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net This adds the ability for sphinx, a tool for creating html documentation to read in .rst documentation files. It also enables it to use the breathe plugin to read in xml files that are generated by doxygen, a code documentation tool. Sphinx pulls in rst or xml documentation and generates pretty html which also conveniently can be hosted by readthedocs.org. The requirements.txt file tells sphinx that it requires the 'breathe' plugin to be installed. breathe is a plugin that acts as the translation layer between doxygen and sphinx. Signed-off-by: grantseltzer --- tools/lib/bpf/docs/conf.py | 38 ++++++++++++++++++++++ tools/lib/bpf/docs/index.rst | 15 +++++++++ tools/lib/bpf/docs/sphinx/Makefile | 9 +++++ tools/lib/bpf/docs/sphinx/requirements.txt | 1 + 4 files changed, 63 insertions(+) create mode 100644 tools/lib/bpf/docs/conf.py create mode 100644 tools/lib/bpf/docs/index.rst create mode 100644 tools/lib/bpf/docs/sphinx/Makefile create mode 100644 tools/lib/bpf/docs/sphinx/requirements.txt diff --git a/tools/lib/bpf/docs/conf.py b/tools/lib/bpf/docs/conf.py new file mode 100644 index 000000000..a67dff0dd --- /dev/null +++ b/tools/lib/bpf/docs/conf.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import subprocess + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', + 'sphinx.ext.imgmath', + 'sphinx.ext.todo', + 'breathe', +] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' + +if read_the_docs_build: + subprocess.call('make clean', shell=True) + subprocess.call('cd sphinx/doxygen ; doxygen', shell=True) + +html_theme = 'sphinx_rtd_theme' + +breathe_projects = { "libbpf": "./sphinx/doxygen/build/xml/" } +breathe_default_project = "libbpf" +breathe_show_define_initializer = True +breathe_show_enumvalue_initializer = True diff --git a/tools/lib/bpf/docs/index.rst b/tools/lib/bpf/docs/index.rst new file mode 100644 index 000000000..31a6ecfab --- /dev/null +++ b/tools/lib/bpf/docs/index.rst @@ -0,0 +1,15 @@ +libbpf documentation +======================================= + +This is documentation for libbpf, a userspace library for loading and +interacting with bpf programs. + +All general BPF questions, including kernel functionality, libbpf APIs and +their application, should be sent to bpf@vger.kernel.org mailing list. +You can subscribe to it `here `_ +and search its archive `here `_. +Please search the archive before asking new questions. It very well might +be that this was already addressed or answered before. + +.. toctree:: + :caption: Documentation: diff --git a/tools/lib/bpf/docs/sphinx/Makefile b/tools/lib/bpf/docs/sphinx/Makefile new file mode 100644 index 000000000..69305958f --- /dev/null +++ b/tools/lib/bpf/docs/sphinx/Makefile @@ -0,0 +1,9 @@ +SPHINXBUILD ?= sphinx-build +SOURCEDIR = .. +BUILDDIR = build + +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" + +%: + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" diff --git a/tools/lib/bpf/docs/sphinx/requirements.txt b/tools/lib/bpf/docs/sphinx/requirements.txt new file mode 100644 index 000000000..188f51e62 --- /dev/null +++ b/tools/lib/bpf/docs/sphinx/requirements.txt @@ -0,0 +1 @@ +breathe \ No newline at end of file From patchwork Thu Apr 29 05:47:33 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Grant Seltzer Richman X-Patchwork-Id: 12231983 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-14.7 required=3.0 tests=BAYES_00,DATE_IN_PAST_12_24, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,UPPERCASE_75_100,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id EEEB1C433B4 for ; Thu, 29 Apr 2021 21:41:04 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id C2B8461466 for ; Thu, 29 Apr 2021 21:41:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237204AbhD2Vlu (ORCPT ); Thu, 29 Apr 2021 17:41:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51754 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234837AbhD2Vlt (ORCPT ); Thu, 29 Apr 2021 17:41:49 -0400 Received: from mail-qk1-x72e.google.com (mail-qk1-x72e.google.com [IPv6:2607:f8b0:4864:20::72e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id E3912C06138C for ; Thu, 29 Apr 2021 14:41:02 -0700 (PDT) Received: by mail-qk1-x72e.google.com with SMTP id o5so68802063qkb.0 for ; Thu, 29 Apr 2021 14:41:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=7N4W24reCRk4JmUbPCfP10EVmpvZYDdRbmAGafvM9O8=; b=fuBQb978uPyUp486mOyDjfycdBhqAWEsaw9IXS5d+zGWYtXfyPQpzowtxTwU1XhNol e9za6oHbiEB9B94IiCmVSC/mt4LixhS+E+I6rihnrZTijdoZDtq+tBeT8mrtdUatcYQv hgcjEdKtIrOFSRmdm18qIvtIKCz9zVjtro5Rmp/cIQACXhXmDrRhUqTaK2LfR4jBqB6l Eal1WaW0pYTWwTjWKW6z+nDjq4aQxFrzrCidPoC+8oOdxP5vSeDmlwIAFOfVqLJmf4Ka Jz4c35eiX/3QZB+hAPmECnwOUk3zbfr6llExfnUuDAU5dWtaQq+4fWQ30aHKfqysZ7h+ tTTg== 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:mime-version:content-transfer-encoding; bh=7N4W24reCRk4JmUbPCfP10EVmpvZYDdRbmAGafvM9O8=; b=RISu1rgcGyTMX5mEzwx+5vZAG5aNW633l+bzfMndIYOS7oXr2KjSoaxLw/1axewSGz LSAOp7KFtcUABxwIf528tEdLM5FFYeWWr5LPq2maqRDPRJ+wMaWhIL34dYn7gWzelZVZ lV6W4auMkQIHgryva89hjUk+ZsyrKn2E+56Qsq3jlJ1n1zNd9gXrNyXAjwelLkPRhDwk i5WOVgVt75Px748S2PbLLrhzed1ziL+HGPhmxbSdgZfZhHXc9/bUFzd5Ee/+PZyxwzfg gVh+Ysi04l7hc940ipA5L8dw11tYFsKTJMwirzLyhFDQ9YqxX1DtfH3QqNGPrlh2BFTx RrAg== X-Gm-Message-State: AOAM531+BWxLzn5hdr+CYAcetidn9ZjPceMH6LENg03HYkjJyfMitqFh wBocO3uTGFJaRl2sFBNGbM4= X-Google-Smtp-Source: ABdhPJxWrSrf+Js0U/xFchMEDwwnHUiXPqffgJ+YJoqKEcKi7+DxvNhpyW6IOfxAI2qGo3lwByUrXg== X-Received: by 2002:a05:620a:a4e:: with SMTP id j14mr1777548qka.441.1619732462179; Thu, 29 Apr 2021 14:41:02 -0700 (PDT) Received: from localhost.localdomain (pool-100-33-2-40.nycmny.fios.verizon.net. [100.33.2.40]) by smtp.gmail.com with ESMTPSA id m16sm2993869qkm.100.2021.04.29.14.41.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Apr 2021 14:41:01 -0700 (PDT) From: grantseltzer To: andrii@kernel.org, daniel@iogearbox.net Cc: grantseltzer@gmail.com, bpf@vger.kernel.org Subject: [PATCH bpf-next 2/3] bpf: Add doxygen configuration file Date: Thu, 29 Apr 2021 05:47:33 +0000 Message-Id: <20210429054734.53264-3-grantseltzer@gmail.com> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20210429054734.53264-1-grantseltzer@gmail.com> References: <20210429054734.53264-1-grantseltzer@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net This adds Doxyfile, the configuration file for Doxygen. It can be evoked by navigating to it's containing directory and running `doxygen`. Doxyfile is the default filename. Evoking sphinx from the tools/lib/bpf/sphinx directory will also evoke doxygen. This integrates doxygen XML output into sphinx HTML output. The majority of these configuraiton settings are defaults, the main important settings are INPUT, OUTPUT_DIRECTORY, GENERATE_XML, EXCLUDE_SYMBOLS, and OPTIMIZE_OUTPUT_FOR_C. Signed-off-by: grantseltzer --- tools/lib/bpf/docs/sphinx/doxygen/Doxyfile | 320 +++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 tools/lib/bpf/docs/sphinx/doxygen/Doxyfile diff --git a/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile b/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile new file mode 100644 index 000000000..905eace7b --- /dev/null +++ b/tools/lib/bpf/docs/sphinx/doxygen/Doxyfile @@ -0,0 +1,320 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "libbpf" +PROJECT_NUMBER = +PROJECT_BRIEF = +PROJECT_LOGO = +OUTPUT_DIRECTORY = ./build +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +OUTPUT_TEXT_DIRECTION = None +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +RESOLVE_UNNAMED_PARAMS = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +INPUT = ../../.. +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ + *.m \ + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f18 \ + *.f \ + *.for \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf \ + *.ice +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = ___* +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = YES +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +ALPHABETICAL_INDEX = YES +IGNORE_PREFIX = +GENERATE_HTML = NO +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = NO +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +HTML_FORMULA_FORMAT = png +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +FORMULA_MACROFILE = +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2 +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = +MAKEINDEX_CMD_NAME = makeindex +LATEX_MAKEINDEX_CMD = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain +LATEX_TIMESTAMP = NO +LATEX_EMOJI_DIRECTORY = +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +RTF_SOURCE_CODE = NO +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_SUBDIR = +MAN_LINKS = NO +GENERATE_XML = YES +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +XML_NS_MEMB_FILE_SCOPE = NO +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +CLASS_DIAGRAMS = YES +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES From patchwork Thu Apr 29 05:47:34 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Grant Seltzer Richman X-Patchwork-Id: 12231985 X-Patchwork-Delegate: bpf@iogearbox.net Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-19.7 required=3.0 tests=BAYES_00,DATE_IN_PAST_12_24, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1CDD9C43461 for ; Thu, 29 Apr 2021 21:41:06 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id E83F961464 for ; Thu, 29 Apr 2021 21:41:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S237254AbhD2Vlw (ORCPT ); Thu, 29 Apr 2021 17:41:52 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:51764 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S237191AbhD2Vlv (ORCPT ); Thu, 29 Apr 2021 17:41:51 -0400 Received: from mail-qt1-x833.google.com (mail-qt1-x833.google.com [IPv6:2607:f8b0:4864:20::833]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AE164C06138B for ; Thu, 29 Apr 2021 14:41:04 -0700 (PDT) Received: by mail-qt1-x833.google.com with SMTP id j19so10000963qtx.13 for ; Thu, 29 Apr 2021 14:41:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=iYJ7E1heEgvxDeqLZnL4sn6H/CCcIRlNBxrxvMONl3o=; b=NZkk/evOKyx6ICNq6FDsC7XW9ZgERmufjyIg9vMpv3N2dUVcKIluOV6Ez4/1fSOAw0 sktsd1L8N6Vq2EYcTBPrTIiDHFBfjiQ9IfYQyhLTPeA85EHYFSYK5JKxZ3MnXshcHq/5 gyf7/rXknjp9j+YA5cqPkHr4QG13bZC6Tf8w4qL0N1uGWbj3oHjJm8GnJhjU9MToVbpS XHsdAtpwCvHK8LLn/GE05kjWpE9Wm/fdnwqWulBOT4PheQRhNRfvqnLid1939CkY2Bhp ht5MbGR9AzbGO3s5mTIhOt00bQakxyeprk0aAVHCEAYwO/XJxKrXBWuLH9aPN7YGrWbO Tp3w== 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:mime-version:content-transfer-encoding; bh=iYJ7E1heEgvxDeqLZnL4sn6H/CCcIRlNBxrxvMONl3o=; b=taHzn0iCy0/CQaPtLaBuZE/dwj3p2g2by2GGuf6H3JMVTMwN6calSTDobl8oE8jOqO wytcLdC8Fd2GWxOJcfp8BrgrjGYVGOi/qV3QeA5VvDsgtxwtudi/3NewNFXeDXNBnrxK ghzMacVxWHLMDzL9XGSv1M/cEAPX/1klbH5vqUS4//6HRFUQh8DW0CkJt1/L53US/RsS dUkbOb/Iq0D4/MO7iXyoCSwFt4MzpFGbZjwtu/d0/EDZdw/TStC8ZNgGS96A3qUmUonE eHE90VRljR3XZa86Tt22gk2ka1tt+2Rkoh4IA7VoP96z2JV8rz1RKFEUvYiw+Cy6q9Y8 USrw== X-Gm-Message-State: AOAM5338l5u1sx27EodYqH9QrBslFEvvA2nHqOvQhR8RdTaOLbSQLJLJ Z+y0LN1r5RkyLz2lf/6/0yU= X-Google-Smtp-Source: ABdhPJwyQExJmDprSPeKzZKCwtugNowKT+nL1xNjTAK6WQN0GUsTtkPJaiLpigfwm283YcXGiamEwQ== X-Received: by 2002:ac8:530f:: with SMTP id t15mr1487250qtn.189.1619732463922; Thu, 29 Apr 2021 14:41:03 -0700 (PDT) Received: from localhost.localdomain (pool-100-33-2-40.nycmny.fios.verizon.net. [100.33.2.40]) by smtp.gmail.com with ESMTPSA id m16sm2993869qkm.100.2021.04.29.14.41.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Apr 2021 14:41:03 -0700 (PDT) From: grantseltzer To: andrii@kernel.org, daniel@iogearbox.net Cc: grantseltzer@gmail.com, bpf@vger.kernel.org Subject: [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf Date: Thu, 29 Apr 2021 05:47:34 +0000 Message-Id: <20210429054734.53264-4-grantseltzer@gmail.com> X-Mailer: git-send-email 2.29.2 In-Reply-To: <20210429054734.53264-1-grantseltzer@gmail.com> References: <20210429054734.53264-1-grantseltzer@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: bpf@vger.kernel.org X-Patchwork-Delegate: bpf@iogearbox.net This adds rst files containg documentation files relevant for libbpf development. naming_convention.rst is pulled from the previous README.rst file. api.rst is an index page that links to the api documentation generationg from doxygen+breathe. Signed-off-by: grantseltzer --- tools/lib/bpf/docs/api.rst | 60 +++++++++++++++++++ tools/lib/bpf/docs/build.rst | 39 ++++++++++++ tools/lib/bpf/docs/index.rst | 6 ++ .../naming_convention.rst} | 18 +++--- 4 files changed, 116 insertions(+), 7 deletions(-) create mode 100644 tools/lib/bpf/docs/api.rst create mode 100644 tools/lib/bpf/docs/build.rst rename tools/lib/bpf/{README.rst => docs/naming_convention.rst} (97%) diff --git a/tools/lib/bpf/docs/api.rst b/tools/lib/bpf/docs/api.rst new file mode 100644 index 000000000..36bac417b --- /dev/null +++ b/tools/lib/bpf/docs/api.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +.. _api: + +.. contents:: Table of Contents + :local: + :depth: 1 + +LIBBPF API +================== + + +libbpf.h +------------------ + +.. doxygenfile:: libbpf.h + :project: libbpf + +bpf_core_read.h +------------------ + +.. doxygenfile:: bpf_core_read.h + :project: libbpf + +btf.h +------------------ + +.. doxygenfile:: btf.h + :project: libbpf + +bpf_endian.h +------------------ + +.. doxygenfile:: bpf_endian.h + :project: libbpf + +libbpf_common.h +------------------ + +.. doxygenfile:: libbpf_common.h + :project: libbpf + +hashmap.h +------------------ + +.. doxygenfile:: hashmap.h + :project: libbpf + + +bpf_helpers.h +------------------ + +.. doxygenfile:: bpf_helpers.h + :project: libbpf + +bpf_helper_defs.h +------------------ + +.. doxygenfile:: hashmap.h + :project: libbpf diff --git a/tools/lib/bpf/docs/build.rst b/tools/lib/bpf/docs/build.rst new file mode 100644 index 000000000..749f96dd2 --- /dev/null +++ b/tools/lib/bpf/docs/build.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + +.. _build: + +Building libbpf +======================================= + +libelf is an internal dependency of libbpf and thus it is required to link +against and must be installed on the system for applications to work. +pkg-config is used by default to find libelf, and the program called +can be overridden with PKG_CONFIG. + +If using pkg-config at build time is not desired, it can be disabled by +setting NO_PKG_CONFIG=1 when calling make. + +To build both static libbpf.a and shared libbpf.so: + +.. code-block:: bash + + $ cd src + $ make + +To build only static libbpf.a library in directory build/ and install them +together with libbpf headers in a staging directory root/: + +.. code-block:: bash + + $ cd src + $ mkdir build root + $ BUILD_STATIC_ONLY=y OBJDIR=build DESTDIR=root make install + +To build both static libbpf.a and shared libbpf.so against a custom libelf +dependency installed in /build/root/ and install them together with libbpf +headers in a build directory /build/root/: + +.. code-block:: bash + + $ cd src + $ PKG_CONFIG_PATH=/build/root/lib64/pkgconfig DESTDIR=/build/root make \ No newline at end of file diff --git a/tools/lib/bpf/docs/index.rst b/tools/lib/bpf/docs/index.rst index 31a6ecfab..76bb93580 100644 --- a/tools/lib/bpf/docs/index.rst +++ b/tools/lib/bpf/docs/index.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) + libbpf documentation ======================================= @@ -13,3 +15,7 @@ be that this was already addressed or answered before. .. toctree:: :caption: Documentation: + + api + naming_convention + build \ No newline at end of file diff --git a/tools/lib/bpf/README.rst b/tools/lib/bpf/docs/naming_convention.rst similarity index 97% rename from tools/lib/bpf/README.rst rename to tools/lib/bpf/docs/naming_convention.rst index 8928f7787..6b9ae9701 100644 --- a/tools/lib/bpf/README.rst +++ b/tools/lib/bpf/docs/naming_convention.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) -libbpf API naming convention +.. _naming_convention: + +API naming convention ============================ libbpf API provides access to a few logically separated groups of @@ -76,7 +78,7 @@ Please take a look at Documentation/networking/af_xdp.rst in the Linux kernel source tree on how to use XDP sockets and for some common mistakes in case you do not get any traffic up to user space. -libbpf ABI +ABI ========== libbpf can be both linked statically or used as DSO. To avoid possible @@ -116,7 +118,8 @@ This bump in ABI version is at most once per kernel development cycle. For example, if current state of ``libbpf.map`` is: -.. code-block:: +.. code-block:: c + LIBBPF_0.0.1 { global: bpf_func_a; @@ -128,7 +131,8 @@ For example, if current state of ``libbpf.map`` is: , and a new symbol ``bpf_func_c`` is being introduced, then ``libbpf.map`` should be changed like this: -.. code-block:: +.. code-block:: c + LIBBPF_0.0.1 { global: bpf_func_a; @@ -148,7 +152,7 @@ Format of version script and ways to handle ABI changes, including incompatible ones, described in details in [1]. Stand-alone build -================= +------------------- Under https://github.com/libbpf/libbpf there is a (semi-)automated mirror of the mainline's version of libbpf for a stand-alone build. @@ -157,12 +161,12 @@ However, all changes to libbpf's code base must be upstreamed through the mainline kernel tree. License -======= +------------------- libbpf is dual-licensed under LGPL 2.1 and BSD 2-Clause. Links -===== +------------------- [1] https://www.akkadia.org/drepper/dsohowto.pdf (Chapter 3. Maintaining APIs and ABIs).