From d838d821c9687a789673b2ac9dff707fdc599e1e Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:29 +0100 Subject: [PATCH 01/12] meson: wire up support for AsciiDoctor While our Makefile supports both Asciidoc and AsciiDoctor, our Meson build instructions only support the former. Wire up support for the latter, as well. Our Makefile always favors Asciidoc, but Meson will automatically figure out which of both to use based on whether they are installed or not. To keep compatibility with our Makefile it favors Asciidoc over Asciidoctor in case both are available. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 110 ++++++++++++++++++++++++++++---------- meson_options.txt | 2 + 2 files changed, 84 insertions(+), 28 deletions(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index fca3eab1f1360a..acd6d86ec779e6 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -204,29 +204,87 @@ manpages = { 'gitworkflows.txt' : 7, } -asciidoc = find_program('asciidoc') -git = find_program('git', required: false) -xmlto = find_program('xmlto') +docs_backend = get_option('docs_backend') +if docs_backend == 'auto' + if find_program('asciidoc', required: false).found() + docs_backend = 'asciidoc' + elif find_program('asciidoctor', required: false).found() + docs_backend = 'asciidoctor' + else + error('Neither asciidoc nor asciidoctor were found.') + endif +endif -asciidoc_conf = custom_target( - command: [ - shell, - meson.project_source_root() / 'GIT-VERSION-GEN', - meson.project_source_root(), - '@INPUT@', - '@OUTPUT@', - ], - input: meson.current_source_dir() / 'asciidoc.conf.in', - output: 'asciidoc.conf', - depends: [git_version_file], - env: version_gen_environment, -) +if docs_backend == 'asciidoc' + asciidoc = find_program('asciidoc', required: true) + asciidoc_html = 'xhtml11' + asciidoc_docbook = 'docbook' + xmlto_extra = [ ] -asciidoc_common_options = [ - asciidoc, - '--conf-file=' + asciidoc_conf.full_path(), - '--attribute=build_dir=' + meson.current_build_dir(), -] + asciidoc_conf = custom_target( + command: [ + shell, + meson.project_source_root() / 'GIT-VERSION-GEN', + meson.project_source_root(), + '@INPUT@', + '@OUTPUT@', + ], + input: meson.current_source_dir() / 'asciidoc.conf.in', + output: 'asciidoc.conf', + depends: [git_version_file], + env: version_gen_environment, + ) + + asciidoc_common_options = [ + asciidoc, + '--conf-file=' + asciidoc_conf.full_path(), + '--attribute=build_dir=' + meson.current_build_dir(), + ] + + documentation_deps = [ + asciidoc_conf, + ] +elif docs_backend == 'asciidoctor' + asciidoctor = find_program('asciidoctor', required: true) + asciidoc_html = 'xhtml5' + asciidoc_docbook = 'docbook5' + xmlto_extra = [ + '--skip-validation', + '-x', meson.current_source_dir() / 'manpage.xsl', + ] + + asciidoctor_extensions = custom_target( + command: [ + shell, + meson.project_source_root() / 'GIT-VERSION-GEN', + meson.project_source_root(), + '@INPUT@', + '@OUTPUT@', + ], + input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in', + output: 'asciidoctor-extensions.rb', + depends: [git_version_file], + env: version_gen_environment, + ) + + asciidoc_common_options = [ + asciidoctor, + '--attribute', 'compat-mode', + '--attribute', 'tabsize=8', + '--attribute', 'litdd=--', + '--attribute', 'docinfo=shared', + '--attribute', 'build_dir=' + meson.current_build_dir(), + '--load-path', meson.current_build_dir(), + '--require', 'asciidoctor-extensions', + ] + + documentation_deps = [ + asciidoctor_extensions, + ] +endif + +git = find_program('git', required: false) +xmlto = find_program('xmlto') cmd_lists = [ 'cmds-ancillaryinterrogators.txt', @@ -243,10 +301,6 @@ cmd_lists = [ 'cmds-foreignscminterface.txt', ] -documentation_deps = [ - asciidoc_conf, -] - documentation_deps += custom_target( command: [ perl, @@ -278,7 +332,7 @@ foreach manpage, category : manpages if get_option('docs').contains('man') manpage_xml_target = custom_target( command: asciidoc_common_options + [ - '--backend=docbook', + '--backend=' + asciidoc_docbook, '--doctype=manpage', '--out-file=@OUTPUT@', meson.current_source_dir() / manpage, @@ -301,7 +355,7 @@ foreach manpage, category : manpages manpage_xml_target, '-o', meson.current_build_dir(), - ], + ] + xmlto_extra, output: manpage_path, install: true, install_dir: get_option('mandir') / 'man' + category.to_string(), @@ -311,7 +365,7 @@ foreach manpage, category : manpages if get_option('docs').contains('html') and category == 1 custom_target( command: asciidoc_common_options + [ - '--backend=xhtml11', + '--backend=' + asciidoc_html, '--doctype=manpage', '--out-file=@OUTPUT@', meson.current_source_dir() / manpage, diff --git a/meson_options.txt b/meson_options.txt index 4be7eab3993917..f50bb40cdf6046 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -85,6 +85,8 @@ option('docs', type: 'array', choices: ['man', 'html'], value: [], description: 'Which documenattion formats to build and install.') option('default_help_format', type: 'combo', choices: ['man', 'html'], value: 'man', description: 'Default format used when executing git-help(1).') +option('docs_backend', type: 'combo', choices: ['asciidoc', 'asciidoctor', 'auto'], value: 'auto', + description: 'Which backend to use to generate documentation.') # Testing. option('tests', type: 'boolean', value: true, From 2a8bd34c5576e02fed38d85dc5c90ffb9d4ecfb3 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:30 +0100 Subject: [PATCH 02/12] meson: properly wire up dependencies for our docs A couple of Meson documentation targets use `meson.current_source_dir()` to resolve inputs. This has the downside that it does not automagically make Meson track these inputs as a dependency. After all, string arguments really can be anything, even if they happen to match an actual filesystem path. Adapt these build targets to instead use inputs. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index acd6d86ec779e6..b3c8b6c56339e1 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -229,7 +229,7 @@ if docs_backend == 'asciidoc' '@INPUT@', '@OUTPUT@', ], - input: meson.current_source_dir() / 'asciidoc.conf.in', + input: 'asciidoc.conf.in', output: 'asciidoc.conf', depends: [git_version_file], env: version_gen_environment, @@ -261,7 +261,7 @@ elif docs_backend == 'asciidoctor' '@INPUT@', '@OUTPUT@', ], - input: meson.current_source_dir() / 'asciidoctor-extensions.rb.in', + input: 'asciidoctor-extensions.rb.in', output: 'asciidoctor-extensions.rb', depends: [git_version_file], env: version_gen_environment, @@ -304,10 +304,11 @@ cmd_lists = [ documentation_deps += custom_target( command: [ perl, - meson.current_source_dir() / 'cmd-list.perl', + '@INPUT@', meson.project_source_root(), meson.current_build_dir(), ] + cmd_lists, + input: 'cmd-list.perl', output: cmd_lists ) @@ -315,7 +316,7 @@ foreach mode : [ 'diff', 'merge' ] documentation_deps += custom_target( command: [ shell, - meson.current_source_dir() / 'generate-mergetool-list.sh', + '@INPUT@', '..', 'diff', '@OUTPUT@' @@ -324,6 +325,7 @@ foreach mode : [ 'diff', 'merge' ] 'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools', 'TOOL_MODE=' + mode, ], + input: 'generate-mergetool-list.sh', output: 'mergetools-' + mode + '.txt', ) endforeach @@ -335,9 +337,10 @@ foreach manpage, category : manpages '--backend=' + asciidoc_docbook, '--doctype=manpage', '--out-file=@OUTPUT@', - meson.current_source_dir() / manpage, + '@INPUT@', ], depends: documentation_deps, + input: manpage, output: fs.stem(manpage) + '.xml', ) @@ -345,10 +348,8 @@ foreach manpage, category : manpages manpage_target = custom_target( command: [ xmlto, - '-m', - meson.current_source_dir() / 'manpage-normal.xsl', - '-m', - meson.current_source_dir() / 'manpage-bold-literal.xsl', + '-m', '@INPUT0@', + '-m', '@INPUT1@', '--stringparam', 'man.base.url.for.relative.links=' + get_option('prefix') / get_option('mandir'), 'man', @@ -356,6 +357,10 @@ foreach manpage, category : manpages '-o', meson.current_build_dir(), ] + xmlto_extra, + input: [ + 'manpage-normal.xsl', + 'manpage-bold-literal.xsl', + ], output: manpage_path, install: true, install_dir: get_option('mandir') / 'man' + category.to_string(), @@ -368,9 +373,10 @@ foreach manpage, category : manpages '--backend=' + asciidoc_html, '--doctype=manpage', '--out-file=@OUTPUT@', - meson.current_source_dir() / manpage, + '@INPUT@', ], depends: documentation_deps, + input: manpage, output: fs.stem(manpage) + '.html', install: true, install_dir: get_option('datadir') / 'doc/git-doc', From b88540045c3d70dbf4138c8f32209fea32e40d90 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:31 +0100 Subject: [PATCH 03/12] meson: fix generation of merge tools Our buildsystems generate a list of diff and merge tools that ultimately end up in our documentation. And while Meson does wire up the logic, it tries to use the TOOL_MODE environment variable to set up the mode. This is wrong though: the mode is set via an argument that we have fixed to 'diff' mode by accident. Fix this such that merge tools are properly generated. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index b3c8b6c56339e1..c2512328ca9b76 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -318,12 +318,11 @@ foreach mode : [ 'diff', 'merge' ] shell, '@INPUT@', '..', - 'diff', + mode, '@OUTPUT@' ], env: [ 'MERGE_TOOLS_DIR=' + meson.project_source_root() / 'mergetools', - 'TOOL_MODE=' + mode, ], input: 'generate-mergetool-list.sh', output: 'mergetools-' + mode + '.txt', From 0696ebe9ce533cf3c839c9eb2bd2331c8fa0f014 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:32 +0100 Subject: [PATCH 04/12] meson: generate HTML pages for all man page categories When generating HTML pages for our man pages we only generate them for category 1 in Meson, which are the pages corresponding to our built-in commands. I cannot tell why I added this filter though: our Makefile installs all man pages, so a Meson-based build misses out on many of them. Fix this by removing the filter. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index c2512328ca9b76..48583e9a7f4b03 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -366,7 +366,7 @@ foreach manpage, category : manpages ) endif - if get_option('docs').contains('html') and category == 1 + if get_option('docs').contains('html') custom_target( command: asciidoc_common_options + [ '--backend=' + asciidoc_html, From 851ecc4290cbdb57f36f10b77da9c1ae13c10469 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:33 +0100 Subject: [PATCH 05/12] Documentation: inline user-manual.conf When generating our user manual we set up a bit of extra configuration compared to our normal configuration. This is done by having an extra "user-manual.conf" file that Asciidoc seems to pull in automatically due to matching filenames with "user-manual.txt". This dependency is quite hidden though and thus easy to miss. Furthermore, it seems that Asciidoc does not know to pull it in for out-of-tree builds where we use relative paths. The setup in AsciiDoctor is somewhat different: instead of having two sets of configuration, we condition the use of manual-specific configs based on whether the document type is "book". And as we only build our user manual with that type this is sufficient. Use the same trick for our user manual by inlining the configuration into "asciidoc.conf.in" and making it conditional on whether or not "doctype-book" is defined. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- Documentation/asciidoc.conf.in | 10 ++++++++++ Documentation/user-manual.conf | 11 ----------- 3 files changed, 11 insertions(+), 12 deletions(-) delete mode 100644 Documentation/user-manual.conf diff --git a/Documentation/Makefile b/Documentation/Makefile index a89823e1d1ee50..4f152077dded75 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -362,7 +362,7 @@ manpage-cmd = $(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< %.xml : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $< -user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC_DEPS) +user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_XML) -d book -o $@ $< technical/api-index.txt: technical/api-index-skel.txt \ diff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in index b89bccf2309d78..f2aef6cb79f47c 100644 --- a/Documentation/asciidoc.conf.in +++ b/Documentation/asciidoc.conf.in @@ -25,12 +25,22 @@ manmanual=Git Manual mansource=Git @GIT_VERSION@ revdate=@GIT_DATE@ +ifdef::doctype-book[] +[titles] + underlines="__","==","--","~~","^^" +endif::doctype-book[] + ifdef::backend-docbook[] [linkgit-inlinemacro] +ifndef::doctype-book[] {0%{target}} {0#} {0#{target}{0}} {0#} +endif::doctype-book[] +ifdef::doctype-book[] +{target}{0?({0})} +endif::doctype-book[] [literal-inlinemacro] {eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\1', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1\2', re.sub(r'(\.\.\.?)([^\]$.])', r'\1\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))} diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf deleted file mode 100644 index 0148f126dcdf6a..00000000000000 --- a/Documentation/user-manual.conf +++ /dev/null @@ -1,11 +0,0 @@ -[titles] - underlines="__","==","--","~~","^^" - -[attributes] -caret=^ -startsb=[ -endsb=] -tilde=~ - -[linkgit-inlinemacro] -{target}{0?({0})} From ae0b33939d233fa340f1ebb768588dc46a128e4c Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:34 +0100 Subject: [PATCH 06/12] meson: generate user manual Our documentation contains a user manual that gives people a short introduction to Git. Our Makefile knows to generate the manual into three different formats: an HTML page, a PDF and an info page. The Meson build instructions don't yet generate any of these. While wiring up all these formats I hit a couple of road blocks with how we generate our info pages. Even though I eventually resolved these, it made me question whether anybody actually uses info pages in the first place. Checking through a couple of downstream consumers I couldn't find a single user of either the info pages nor of our PDF manual in Arch Linux, Debian, Fedora, Ubuntu, FreeBSD or OpenBSDFedora. So it's rather safe to assume that there aren't really any users out there, and thus the added complexity does not seem worth it. Wire up support for building the user manual in HTML format and conciously skip over the other two formats. This is basically a form of silent deprecation: if people out there use the other two formats they will eventually complain about them missing in Meson, which means we can wire them up at a later point. If they don't we can phase out these formats eventually. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/Documentation/meson.build b/Documentation/meson.build index 48583e9a7f4b03..404cb20d10a2fb 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -382,3 +382,35 @@ foreach manpage, category : manpages ) endif endforeach + +if get_option('docs').contains('html') + xsltproc = find_program('xsltproc') + + user_manual_xml = custom_target( + command: asciidoc_common_options + [ + '--backend=' + asciidoc_docbook, + '--doctype=book', + '--out-file=@OUTPUT@', + '@INPUT@', + ], + input: 'user-manual.txt', + output: 'user-manual.xml', + depends: documentation_deps, + ) + + custom_target( + command: [ + xsltproc, + '--xinclude', + '--stringparam', 'html.stylesheet', 'docbook-xsl.css', + '--param', 'generate.consistent.ids', '1', + '--output', '@OUTPUT@', + '@INPUT@', + user_manual_xml, + ], + input: 'docbook.xsl', + output: 'user-manual.html', + install: true, + install_dir: get_option('datadir') / 'doc/git-doc', + ) +endif From 88e08b92e9a55fa453d44b26061a6a67a7eefafc Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:35 +0100 Subject: [PATCH 07/12] Documentation: refactor "api-index.sh" for out-of-tree builds The "api-index.sh" script generates an index of API-related documentation. The script does not handle out-of-tree builds and thus cannot be used easily by Meson. Refactor it to be independent of locations by both accepting a source directory where the API docs live as well as a path to an output file. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/Makefile | 2 +- Documentation/technical/api-index.sh | 19 +++++++++++++++---- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f152077dded75..b2d146c44f4ded 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -367,7 +367,7 @@ user-manual.xml: user-manual.txt $(ASCIIDOC_DEPS) technical/api-index.txt: technical/api-index-skel.txt \ technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) - $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh + $(QUIET_GEN)'$(SHELL_PATH_SQ)' technical/api-index.sh ./technical ./technical/api-index.txt technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../ $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt \ diff --git a/Documentation/technical/api-index.sh b/Documentation/technical/api-index.sh index 9c3f4131b85864..296488557434b7 100755 --- a/Documentation/technical/api-index.sh +++ b/Documentation/technical/api-index.sh @@ -1,6 +1,17 @@ #!/bin/sh +if test $# -ne 2 +then + echo >&2 "USAGE: $0 " + exit 1 +fi + +SOURCE_DIR="$1" +OUTPUT="$2" + ( + cd "$SOURCE_DIR" + c=//////////////////////////////////////////////////////////////// skel=api-index-skel.txt sed -e '/^\/\/ table of contents begin/q' "$skel" @@ -18,11 +29,11 @@ done echo "$c" sed -n -e '/^\/\/ table of contents end/,$p' "$skel" -) >api-index.txt+ +) >"$OUTPUT"+ -if test -f api-index.txt && cmp api-index.txt api-index.txt+ >/dev/null +if test -f "$OUTPUT" && cmp "$OUTPUT" "$OUTPUT"+ >/dev/null then - rm -f api-index.txt+ + rm -f "$OUTPUT"+ else - mv api-index.txt+ api-index.txt + mv "$OUTPUT"+ "$OUTPUT" fi From 8922506cb2c34527f8b2321b4f7a4b454a325a07 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:36 +0100 Subject: [PATCH 08/12] Documentation: refactor "howto-index.sh" for out-of-tree builds The "howto-index.sh" is used to generate an index of our how-to docs. It receives as input the paths to these documents, which would typically be relative to the "Documentation/" directory in Makefile-based builds. In an out-of-tree build though it will get relative that may be rooted somewhere else entirely. The file paths do end up in the generated index, and the expectation is that they should always start with "howto/". But for out-of-tree builds we would populate it with the paths relative to the build directory, which is wrong. Fix the issue by using `$(basename "$file")` to generate the path. While at it, move the script into "howto/" to align it with the location of the comparable "api-index.sh" script. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/Makefile | 4 ++-- Documentation/{ => howto}/howto-index.sh | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename Documentation/{ => howto}/howto-index.sh (92%) diff --git a/Documentation/Makefile b/Documentation/Makefile index b2d146c44f4ded..e284ec8b98d618 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -411,8 +411,8 @@ gitman.info: gitman.texi $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml $(QUIET_DB2TEXI)$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@ -howto-index.txt: howto-index.sh $(HOWTO_TXT) - $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(HOWTO_TXT)) >$@ +howto-index.txt: howto/howto-index.sh $(HOWTO_TXT) + $(QUIET_GEN)'$(SHELL_PATH_SQ)' ./howto/howto-index.sh $(sort $(HOWTO_TXT)) >$@ $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt $(ASCIIDOC_DEPS) $(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt diff --git a/Documentation/howto-index.sh b/Documentation/howto/howto-index.sh similarity index 92% rename from Documentation/howto-index.sh rename to Documentation/howto/howto-index.sh index 167b363668b8b5..eecd123a936079 100755 --- a/Documentation/howto-index.sh +++ b/Documentation/howto/howto-index.sh @@ -48,7 +48,7 @@ do file="$txt" fi - echo "* link:$file[$title] $from + echo "* link:howto/$(basename "$file")[$title] $from $abstract " From bcf7edee09e8f9c1779fafa953832f63e9a23545 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:37 +0100 Subject: [PATCH 09/12] meson: generate articles While the Meson build system already knows to generate man pages and our user manual, it does not yet generate the random assortment of articles that we have. Plug this gap. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/howto/meson.build | 62 +++++++++++++++++++++++++++ Documentation/meson.build | 36 ++++++++++++++++ Documentation/technical/meson.build | 66 +++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+) create mode 100644 Documentation/howto/meson.build create mode 100644 Documentation/technical/meson.build diff --git a/Documentation/howto/meson.build b/Documentation/howto/meson.build new file mode 100644 index 00000000000000..c023c104161e61 --- /dev/null +++ b/Documentation/howto/meson.build @@ -0,0 +1,62 @@ +howto_sources = [ + 'coordinate-embargoed-releases.txt', + 'keep-canonical-history-correct.txt', + 'maintain-git.txt', + 'new-command.txt', + 'rebase-from-internal-branch.txt', + 'rebuild-from-update-hook.txt', + 'recover-corrupted-blob-object.txt', + 'recover-corrupted-object-harder.txt', + 'revert-a-faulty-merge.txt', + 'revert-branch-rebase.txt', + 'separating-topic-branches.txt', + 'setup-git-server-over-http.txt', + 'update-hook-example.txt', + 'use-git-daemon.txt', + 'using-merge-subtree.txt', + 'using-signed-tag-in-pull-request.txt', +] + +howto_index = custom_target( + command: [ + shell, + meson.current_source_dir() / 'howto-index.sh', + '@INPUT@', + ], + env: script_environment, + capture: true, + input: howto_sources, + output: 'howto-index.txt', +) + +custom_target( + command: asciidoc_html_options, + input: howto_index, + output: 'howto-index.html', + depends: documentation_deps, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc', +) + +foreach howto : howto_sources + howto_stripped = custom_target( + command: [ + find_program('sed'), + '-e', + '1,/^$/d', + '@INPUT@', + ], + input: howto, + output: fs.stem(howto) + '.stripped', + capture: true, + ) + + custom_target( + command: asciidoc_html_options, + input: howto_stripped, + output: fs.stem(howto_stripped.full_path()) + '.html', + depends: documentation_deps, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc/howto', + ) +endforeach diff --git a/Documentation/meson.build b/Documentation/meson.build index 404cb20d10a2fb..8c6ff0bce1206d 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -413,4 +413,40 @@ if get_option('docs').contains('html') install: true, install_dir: get_option('datadir') / 'doc/git-doc', ) + + articles = [ + 'DecisionMaking.txt', + 'MyFirstContribution.txt', + 'MyFirstObjectWalk.txt', + 'ReviewingGuidelines.txt', + 'SubmittingPatches', + 'ToolsForGit.txt', + 'git-bisect-lk2009.txt', + 'git-tools.txt', + ] + + foreach article : articles + custom_target( + command: asciidoc_common_options + [ + '--backend=' + asciidoc_html, + '--out-file=@OUTPUT@', + '@INPUT@', + ], + input: article, + output: fs.stem(article) + '.html', + depends: documentation_deps, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc', + ) + endforeach + + asciidoc_html_options = asciidoc_common_options + [ + '--backend=' + asciidoc_html, + '--out-file=@OUTPUT@', + '--attribute', 'git-relative-html-prefix=../', + '@INPUT@', + ] + + subdir('howto') + subdir('technical') endif diff --git a/Documentation/technical/meson.build b/Documentation/technical/meson.build new file mode 100644 index 00000000000000..21dfb8b5c9d934 --- /dev/null +++ b/Documentation/technical/meson.build @@ -0,0 +1,66 @@ +api_docs = [ + 'api-error-handling.txt', + 'api-merge.txt', + 'api-parse-options.txt', + 'api-simple-ipc.txt', + 'api-trace2.txt', +] + +articles = [ + 'bitmap-format.txt', + 'build-systems.txt', + 'bundle-uri.txt', + 'commit-graph.txt', + 'directory-rename-detection.txt', + 'hash-function-transition.txt', + 'long-running-process-protocol.txt', + 'multi-pack-index.txt', + 'packfile-uri.txt', + 'pack-heuristics.txt', + 'parallel-checkout.txt', + 'partial-clone.txt', + 'platform-support.txt', + 'racy-git.txt', + 'reftable.txt', + 'remembering-renames.txt', + 'repository-version.txt', + 'rerere.txt', + 'scalar.txt', + 'send-pack-pipeline.txt', + 'shallow.txt', + 'sparse-checkout.txt', + 'sparse-index.txt', + 'trivial-merge.txt', + 'unit-tests.txt', +] + +api_index = custom_target( + command: [ + shell, + meson.current_source_dir() / 'api-index.sh', + meson.current_source_dir(), + '@OUTPUT@', + ], + env: script_environment, + input: api_docs, + output: 'api-index.txt', +) + +custom_target( + command: asciidoc_html_options, + input: api_index, + output: 'api-index.html', + depends: documentation_deps, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc/technical', +) + +foreach article : api_docs + articles + custom_target( + command: asciidoc_html_options, + input: article, + output: fs.stem(article) + '.html', + install: true, + install_dir: get_option('datadir') / 'doc/git-doc/technical', + ) +endforeach From 7a3136e5c713c4a5ed2af51ccb8abb5cfa3d98bf Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:38 +0100 Subject: [PATCH 10/12] meson: install static files for HTML documentation Now that we generate man pages, articles and user manual with Meson the only thing that is still missing in an installation of HTML documents is a couple of static files. Wire these up to finalize Meson's support for generating HTML documentation. Diffing an installation that uses our Makefile with an installation that uses Meson only surfaces a couple of discepancies now: - Meson doesn't install "everyday.html" and "git-remote-helpers.html". These files are marked as obsolete and don't contain any useful information anymore: they simply point to their modern equivalents. - Meson doesn't install "*.txt" files when asking for HTML docs. I'm not sure why our Makefiles do this in the first place, and it does seem like the resulting installation is fully functional even without those files. Other than that, both layout and file contents are the exact same. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/meson.build | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Documentation/meson.build b/Documentation/meson.build index 8c6ff0bce1206d..4d951115650265 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -384,6 +384,27 @@ foreach manpage, category : manpages endforeach if get_option('docs').contains('html') + configure_file( + input: 'docinfo-html.in', + output: 'docinfo.html', + copy: true, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc', + ) + + configure_file( + input: 'docbook-xsl.css', + output: 'docbook-xsl.css', + copy: true, + install: true, + install_dir: get_option('datadir') / 'doc/git-doc', + ) + + install_symlink('index.html', + install_dir: get_option('datadir') / 'doc/git-doc', + pointing_to: 'git.html', + ) + xsltproc = find_program('xsltproc') user_manual_xml = custom_target( From d8af27d309c3637d05bd6b4957b3667c04dc861e Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:39 +0100 Subject: [PATCH 11/12] t/Makefile: make "check-meson" work with Dash The "check-meson" target uses process substitution to check whether extracted contents from "meson.build" match expected contents. Process substitution is unportable though and thus the target will fail when using for example Dash. Fix this by writing data into a temporary directory. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- t/.gitignore | 1 + t/Makefile | 12 +++++++----- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/t/.gitignore b/t/.gitignore index 91cf5772fe5643..3e6b0f2cc57ffe 100644 --- a/t/.gitignore +++ b/t/.gitignore @@ -2,4 +2,5 @@ /test-results /.prove /chainlinttmp +/mesontmp /out/ diff --git a/t/Makefile b/t/Makefile index 290fb03ff011d3..daa5fcae86f348 100644 --- a/t/Makefile +++ b/t/Makefile @@ -103,6 +103,7 @@ clean-except-prove-cache: clean-chainlint clean: clean-except-prove-cache $(RM) -r '$(TEST_RESULTS_DIRECTORY_SQ)' + $(RM) -r mesontmp $(RM) .prove clean-chainlint: @@ -116,16 +117,17 @@ check-chainlint: check-meson: @# awk acts up when trying to match single quotes, so we use \047 instead. - @printf "%s\n" \ + @mkdir -p mesontmp && \ + printf "%s\n" \ "integration_tests t[0-9][0-9][0-9][0-9]-*.sh" \ "unit_test_programs unit-tests/t-*.c" \ "clar_test_suites unit-tests/u-*.c" | \ while read -r variable pattern; do \ - meson_tests=$$(awk "/^$$variable = \[\$$/ {flag=1 ; next } /^]$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047,\$$/, \"\"); print }" meson.build) && \ - actual_tests=$$(ls $$pattern) && \ - if test "$$meson_tests" != "$$actual_tests"; then \ + awk "/^$$variable = \[\$$/ {flag=1 ; next } /^]$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047,\$$/, \"\"); print }" meson.build >mesontmp/meson.txt && \ + ls $$pattern >mesontmp/actual.txt && \ + if ! cmp mesontmp/meson.txt mesontmp/actual.txt; then \ echo "Meson tests differ from actual tests:"; \ - diff -u <(echo "$$meson_tests") <(echo "$$actual_tests"); \ + diff -u mesontmp/meson.txt mesontmp/actual.txt; \ exit 1; \ fi; \ done From 5419445b4d19b0979b14f239fe2362210174f613 Mon Sep 17 00:00:00 2001 From: Patrick Steinhardt Date: Fri, 27 Dec 2024 14:59:40 +0100 Subject: [PATCH 12/12] Documentation: wire up sanity checks for Meson Wire up sanity checks for Meson to verify that no man pages are missing. This check is similar to the same check we already have for our tests. Signed-off-by: Patrick Steinhardt Signed-off-by: Junio C Hamano --- Documentation/.gitignore | 1 + Documentation/Makefile | 16 ++++++++++++++++ Documentation/meson.build | 31 +++++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+) diff --git a/Documentation/.gitignore b/Documentation/.gitignore index 649df89474d357..9f4bb3c4bf9e9e 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -12,6 +12,7 @@ cmds-*.txt mergetools-*.txt SubmittingPatches.txt tmp-doc-diff/ +tmp-meson-diff/ GIT-ASCIIDOCFLAGS /.build/ /GIT-EXCLUDED-PROGRAMS diff --git a/Documentation/Makefile b/Documentation/Makefile index e284ec8b98d618..aedfe99d1d3588 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -339,6 +339,7 @@ clean: $(RM) $(cmds_txt) $(mergetools_txt) *.made $(RM) GIT-ASCIIDOCFLAGS $(RM) asciidoc.conf asciidoctor-extensions.rb + $(RM) -rf tmp-meson-diff docinfo.html: docinfo-html.in $(QUIET_GEN)$(RM) $@ && cat $< >$@ @@ -494,6 +495,20 @@ lint-docs-fsck-msgids: $(LINT_DOCS_FSCK_MSGIDS) lint-docs-manpages: $(QUIET_GEN)./lint-manpages.sh +.PHONY: lint-docs-meson +lint-docs-meson: + @# awk acts up when trying to match single quotes, so we use \047 instead. + @mkdir -p tmp-meson-diff && \ + awk "/^manpages = {$$/ {flag=1 ; next } /^}$$/ { flag=0 } flag { gsub(/^ \047/, \"\"); gsub(/\047 : [157],\$$/, \"\"); print }" meson.build | \ + grep -v -e '#' -e '^$$' | \ + sort >tmp-meson-diff/meson.txt && \ + ls git*.txt scalar.txt | grep -v -e git-bisect-lk2009.txt -e git-tools.txt >tmp-meson-diff/actual.txt && \ + if ! cmp tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; then \ + echo "Meson man pages differ from actual man pages:"; \ + diff -u tmp-meson-diff/meson.txt tmp-meson-diff/actual.txt; \ + exit 1; \ + fi + ## Lint: list of targets above .PHONY: lint-docs lint-docs: lint-docs-fsck-msgids @@ -501,6 +516,7 @@ lint-docs: lint-docs-gitlink lint-docs: lint-docs-man-end-blurb lint-docs: lint-docs-man-section-order lint-docs: lint-docs-manpages +lint-docs: lint-docs-meson ifeq ($(wildcard po/Makefile),po/Makefile) doc-l10n install-l10n:: diff --git a/Documentation/meson.build b/Documentation/meson.build index 4d951115650265..2a26fa8a5fedc0 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -471,3 +471,34 @@ if get_option('docs').contains('html') subdir('howto') subdir('technical') endif + +# Sanity check that we are not missing any tests present in 't/'. This check +# only runs once at configure time and is thus best-effort, only. Furthermore, +# it only verifies man pages for the sake of simplicity. +configured_manpages = manpages.keys() + [ 'git-bisect-lk2009.txt', 'git-tools.txt' ] +actual_manpages = run_command(shell, '-c', 'ls git*.txt scalar.txt', + check: true, + env: script_environment, +).stdout().strip().split('\n') + +if configured_manpages != actual_manpages + missing_manpage = [ ] + foreach actual_manpage : actual_manpages + if actual_manpage not in configured_manpages + missing_manpage += actual_manpage + endif + endforeach + if missing_manpage.length() > 0 + error('Man page found, but not configured:\n\n - ' + '\n - '.join(missing_manpage)) + endif + + superfluous_manpage = [ ] + foreach configured_manpage : configured_manpages + if configured_manpage not in actual_manpages + superfluous_manpage += configured_manpage + endif + endforeach + if superfluous_manpage.length() > 0 + error('Man page configured, but not found:\n\n - ' + '\n - '.join(superfluous_manpage)) + endif +endif