| Message ID | 20220829091500.24115-2-donald.hunter@gmail.com (mailing list archive) |
|---|---|
| State | Changes Requested |
| Delegated to: | BPF |
| Headers | show |
| Series | Add table of BPF program types to docs | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Clearly marked for bpf-next |
| netdev/fixes_present | success | Fixes tag not required for -next series |
| netdev/subject_prefix | success | Link |
| netdev/cover_letter | success | Series has a cover letter |
| netdev/patch_count | success | Link |
| netdev/header_inline | success | No static functions without inline keyword in header files |
| netdev/build_32bit | success | Errors and warnings before: 0 this patch: 0 |
| netdev/cc_maintainers | warning | 2 maintainers not CCed: linux-media@vger.kernel.org mchehab@kernel.org |
| netdev/build_clang | success | Errors and warnings before: 0 this patch: 0 |
| netdev/module_param | success | Was 0 now: 0 |
| netdev/verify_signedoff | success | Signed-off-by tag matches author and committer |
| netdev/check_selftest | success | No net selftest shell script |
| netdev/verify_fixes | success | No Fixes tag |
| netdev/build_allmodconfig_warn | success | Errors and warnings before: 0 this patch: 0 |
| netdev/checkpatch | success | total: 0 errors, 0 warnings, 0 checks, 69 lines checked |
| netdev/kdoc | success | Errors and warnings before: 0 this patch: 0 |
| netdev/source_inline | success | Was 0 now: 0 |
| bpf/vmtest-bpf-next-VM_Test-10 | success | Logs for test_progs on x86_64 with gcc |
| bpf/vmtest-bpf-next-PR | success | PR summary |
| bpf/vmtest-bpf-next-VM_Test-4 | success | Logs for llvm-toolchain |
| bpf/vmtest-bpf-next-VM_Test-5 | success | Logs for set-matrix |
| bpf/vmtest-bpf-next-VM_Test-2 | success | Logs for build for x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-3 | success | Logs for build for x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-1 | success | Logs for build for s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-7 | success | Logs for test_maps on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-8 | success | Logs for test_maps on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-16 | success | Logs for test_verifier on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-17 | success | Logs for test_verifier on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-11 | success | Logs for test_progs on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-13 | success | Logs for test_progs_no_alu32 on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-14 | success | Logs for test_progs_no_alu32 on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-6 | success | Logs for test_maps on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-9 | success | Logs for test_progs on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-12 | success | Logs for test_progs_no_alu32 on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-15 | success | Logs for test_verifier on s390x with gcc |
On 8/29/22 11:14 AM, Donald Hunter wrote: > Run make in list of subdirs to build generated sources and migrate > userspace-api/media to use this instead of being a special case. > > Signed-off-by: Donald Hunter <donald.hunter@gmail.com> Jonathan, given this touches Documentation/Makefile, could you ACK if it looks good to you? Noticed both patches don't have doc: $subj prefix, but that's something we could fix up. Maybe one small request, would be nice to build Documentation/bpf/libbpf/ also with every BPF CI run to avoid breakage of program_types.csv. Donald could you check if feasible? Follow-up might be ok too, but up to Andrii. Thanks, Daniel
Daniel Borkmann <daniel@iogearbox.net> writes: > On 8/29/22 11:14 AM, Donald Hunter wrote: >> Run make in list of subdirs to build generated sources and migrate >> userspace-api/media to use this instead of being a special case. >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > > Jonathan, given this touches Documentation/Makefile, could you ACK if > it looks good to you? Noticed both patches don't have doc: $subj prefix, > but that's something we could fix up. > > Maybe one small request, would be nice to build Documentation/bpf/libbpf/ > also with every BPF CI run to avoid breakage of program_types.csv. Donald > could you check if feasible? Follow-up might be ok too, but up to Andrii. Sure, I can look at what is needed for the BPF CI run. > Thanks, > Daniel
On Tue, Sep 6, 2022 at 3:50 AM Donald Hunter <donald.hunter@gmail.com> wrote: > > Daniel Borkmann <daniel@iogearbox.net> writes: > > > On 8/29/22 11:14 AM, Donald Hunter wrote: > >> Run make in list of subdirs to build generated sources and migrate > >> userspace-api/media to use this instead of being a special case. > >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > > > > Jonathan, given this touches Documentation/Makefile, could you ACK if > > it looks good to you? Noticed both patches don't have doc: $subj prefix, > > but that's something we could fix up. > > > > Maybe one small request, would be nice to build Documentation/bpf/libbpf/ > > also with every BPF CI run to avoid breakage of program_types.csv. Donald > > could you check if feasible? Follow-up might be ok too, but up to Andrii. > > Sure, I can look at what is needed for the BPF CI run. > Daniel (Mueller, not Borkmann), is this something that can be added to BPF CI? > > Thanks, > > Daniel
Andrii Nakryiko <andrii.nakryiko@gmail.com> writes: > On Tue, Sep 6, 2022 at 3:50 AM Donald Hunter <donald.hunter@gmail.com> wrote: >> >> Daniel Borkmann <daniel@iogearbox.net> writes: >> >> > On 8/29/22 11:14 AM, Donald Hunter wrote: >> >> Run make in list of subdirs to build generated sources and migrate >> >> userspace-api/media to use this instead of being a special case. >> >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> >> > >> > Jonathan, given this touches Documentation/Makefile, could you ACK if >> > it looks good to you? Noticed both patches don't have doc: $subj prefix, >> > but that's something we could fix up. >> > >> > Maybe one small request, would be nice to build Documentation/bpf/libbpf/ >> > also with every BPF CI run to avoid breakage of program_types.csv. Donald >> > could you check if feasible? Follow-up might be ok too, but up to Andrii. >> >> Sure, I can look at what is needed for the BPF CI run. >> > > Daniel (Mueller, not Borkmann), is this something that can be added to BPF CI? It looks to me like it can be added to BPF CI if we change docs/conf.py to call a new make target in docs/sphinx/Makefile. Hopefully Daniel can confirm whether this is the case. Given that the tree layouts of the kernel and libbpf are very different I think we need to do one of: 1. Use a separate a .csv generator script with dedicated makefiles per project. 2. Move this entirely to libbpf and include a readthedocs URL in index.rst in the same way as currently done for the API docs. I think my preference would be for 2. Thanks Donald.
On Fri, Sep 09, 2022 at 11:12:22AM +0100, Donald Hunter wrote: > Andrii Nakryiko <andrii.nakryiko@gmail.com> writes: > > > On Tue, Sep 6, 2022 at 3:50 AM Donald Hunter <donald.hunter@gmail.com> wrote: > >> > >> Daniel Borkmann <daniel@iogearbox.net> writes: > >> > >> > On 8/29/22 11:14 AM, Donald Hunter wrote: > >> >> Run make in list of subdirs to build generated sources and migrate > >> >> userspace-api/media to use this instead of being a special case. > >> >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> > >> > > >> > Jonathan, given this touches Documentation/Makefile, could you ACK if > >> > it looks good to you? Noticed both patches don't have doc: $subj prefix, > >> > but that's something we could fix up. > >> > > >> > Maybe one small request, would be nice to build Documentation/bpf/libbpf/ > >> > also with every BPF CI run to avoid breakage of program_types.csv. Donald > >> > could you check if feasible? Follow-up might be ok too, but up to Andrii. > >> > >> Sure, I can look at what is needed for the BPF CI run. > >> > > > > Daniel (Mueller, not Borkmann), is this something that can be added to BPF CI? I think as long as all required packages are available in the CI distribution (which I believe is currently a Ubuntu image, but may in the future become Arch Linux) it should not be a problem to perform checking in CI. It seems as if generating the documentation may take a while, so we should likely try to have it run in a separate job. I can't tell what hidden dependencies there may be, though. > It looks to me like it can be added to BPF CI if we change docs/conf.py > to call a new make target in docs/sphinx/Makefile. Hopefully Daniel can > confirm whether this is the case. I am not familiar with the documentation generation, but my quick search seems to suggest that this is done by a 3rd party service and is decoupled from BPF CI. Specifically, what you suggest may be reflected in the generated docs at https://libbpf.readthedocs.io/, but I believe they are created from the libbpf GitHub repository, which is only infrequently synced from bpf tree sources. I didn't find any indication that CI triggers documentation creation, but it's possible I missed something. [...] Thanks, Daniel
Daniel Müller <deso@posteo.net> writes: > On Fri, Sep 09, 2022 at 11:12:22AM +0100, Donald Hunter wrote: >> Andrii Nakryiko <andrii.nakryiko@gmail.com> writes: >> >> > On Tue, Sep 6, 2022 at 3:50 AM Donald Hunter <donald.hunter@gmail.com> wrote: >> >> >> >> Daniel Borkmann <daniel@iogearbox.net> writes: >> >> >> >> > On 8/29/22 11:14 AM, Donald Hunter wrote: >> >> >> Run make in list of subdirs to build generated sources and migrate >> >> >> userspace-api/media to use this instead of being a special case. >> >> >> Signed-off-by: Donald Hunter <donald.hunter@gmail.com> >> >> > >> >> > Jonathan, given this touches Documentation/Makefile, could you ACK if >> >> > it looks good to you? Noticed both patches don't have doc: $subj prefix, >> >> > but that's something we could fix up. >> >> > >> >> > Maybe one small request, would be nice to build Documentation/bpf/libbpf/ >> >> > also with every BPF CI run to avoid breakage of program_types.csv. Donald >> >> > could you check if feasible? Follow-up might be ok too, but up to Andrii. >> >> >> >> Sure, I can look at what is needed for the BPF CI run. >> >> >> > >> > Daniel (Mueller, not Borkmann), is this something that can be added to BPF CI? > > I think as long as all required packages are available in the CI distribution > (which I believe is currently a Ubuntu image, but may in the future become Arch > Linux) it should not be a problem to perform checking in CI. It seems as if > generating the documentation may take a while, so we should likely try to have > it run in a separate job. I can't tell what hidden dependencies there may be, > though. > >> It looks to me like it can be added to BPF CI if we change docs/conf.py >> to call a new make target in docs/sphinx/Makefile. Hopefully Daniel can >> confirm whether this is the case. > > I am not familiar with the documentation generation, but my quick search seems > to suggest that this is done by a 3rd party service and is decoupled from BPF > CI. Specifically, what you suggest may be reflected in the generated docs at > https://libbpf.readthedocs.io/, but I believe they are created from the libbpf > GitHub repository, which is only infrequently synced from bpf tree sources. I > didn't find any indication that CI triggers documentation creation, but it's > possible I missed something. Apologies, I was referring to the libbpf GitHub repository. Anything committed to the kernel Documentation/bpf/libbpf risks breaking the documentation generation in the libbpf GitHub repository which, as you say, uses readthedocs.
diff --git a/Documentation/Makefile b/Documentation/Makefile index 64d44c1ecad3..8a63ef2dcd1c 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -65,6 +65,12 @@ I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # commands; the 'cmd' from scripts/Kbuild.include is not *loopable* loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; +BUILD_SUBDIRS = \ + Documentation/userspace-api/media + +quiet_cmd_build_subdir = SUBDIR $2 + cmd_build_subdir = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=$2 $3 + # $2 sphinx builder e.g. "html" # $3 name of the build subfolder / e.g. "userspace-api/media", used as: # * dest folder relative to $(BUILDDIR) and @@ -74,7 +80,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit; # e.g. "userspace-api/media" for the linux-tv book-set at ./Documentation/userspace-api/media quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) - cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \ + cmd_sphinx = \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(PYTHON3) $(srctree)/scripts/jobserver-exec \ @@ -93,6 +99,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) htmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),html)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) linkcheckdocs: @@ -100,6 +107,7 @@ linkcheckdocs: latexdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) ifeq ($(HAVE_PDFLATEX),0) @@ -112,6 +120,7 @@ else # HAVE_PDFLATEX pdfdocs: latexdocs @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),latex)) $(foreach var,$(SPHINXDIRS), \ $(MAKE) PDFLATEX="$(PDFLATEX)" LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit; \ mkdir -p $(BUILDDIR)/$(var)/pdf; \ @@ -122,10 +131,12 @@ endif # HAVE_PDFLATEX epubdocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),epub)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var))) xmldocs: @$(srctree)/scripts/sphinx-pre-install --version-check + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),xml)) @+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var))) endif # HAVE_SPHINX @@ -138,7 +149,7 @@ refcheckdocs: cleandocs: $(Q)rm -rf $(BUILDDIR) - $(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean + @+$(foreach var,$(BUILD_SUBDIRS),$(call loop_cmd,build_subdir,$(var),clean)) dochelp: @echo ' Linux kernel internal documentation in different formats from ReST:' diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile index 00922aa7efde..783c6f880b72 100644 --- a/Documentation/userspace-api/media/Makefile +++ b/Documentation/userspace-api/media/Makefile @@ -50,6 +50,8 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception .PHONY: all html epub xml latex all: $(IMGDOT) $(BUILDDIR) ${TARGETS} + @: + html: all epub: all xml: all
Run make in list of subdirs to build generated sources and migrate userspace-api/media to use this instead of being a special case. Signed-off-by: Donald Hunter <donald.hunter@gmail.com> --- Documentation/Makefile | 15 +++++++++++++-- Documentation/userspace-api/media/Makefile | 2 ++ 2 files changed, 15 insertions(+), 2 deletions(-)