mirror/buildroot
1
0
Fork 0
mirror of https://gitlab.com/buildroot.org/buildroot.git synced 2026-09-09 16:01:54 -09:00
Code Issues Packages Projects Releases Wiki Activity

package/doc-asciidoc: fix build for out-of-tree documents

Browse Source 
The doc-asciidoc infra allows document to define sources and resources,
and those can only be local (there is no download support for documents).
The currently documented way to specify those is to use the $(pkgdir)
macro to point to the document sources and resources when they are along
the .mk.

However, this works only for sources and not for resources.

Indeed, sources are used to generate Makefile dependency rules, so
$(pkgdir) is expanded and evaluated during the call to $(doc-asciidoc),
while resources are expanded and evaluated when the rules are executed,
which always happen after all the parsing has be done, at which point
$(pkgdir) expands to the last Makefile that was parsed, which is always
Buildroot's own manual.

This went unnoticed so far because Buildroot's manual is 1) the last to
be parsed, and 2) not using $(pkgdir) anyway.

Additionally, $(pkgdir) is mostly an internal macro, that is, as this
change demonstrates, difficult to use, and thus should not be used, in
packages or in documents.

We fix that by introducing $(FOO_DOCDIR), similar to $(FOO_PKGDIR),
which points to the document directory. We choose not to name the
variable FOO_PKGDIR, because it semantically is not a package.

As a consequence, the last argument to the doc-asciidoc macro is now
superfluous, so it is removed, which causes a little bit of churn in
the main macro. As a further consequence, the third argument in the
inner macro is no longer needed either, so it too is removed, which
causes a bit more churn yet in the inner macro.

Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Cc: Frederic GARDES <frederic.gardes@orange.com>
Signed-off-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be>
This commit is contained in:
Yann E. MORIN
2022-02-01 14:49:44 +01:00
committed by Arnout Vandecappelle (Essensium/Mind)
parent 4c2e266817
commit 4f59ababc0
2 changed files with 59 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/manual/adding-packages-asciidoc.txt
View File

@@ -39,7 +39,7 @@ Here is an example to render a simple AsciiDoc document.
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
08: $(eval $(call asciidoc-document))
----
@@ -85,6 +85,17 @@ various steps:
* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
the specified format +<FMT>+ (see the list of rendered formats, above).
Buildroot sets the following variable that can be used in the definitions
above:
* +$(FOO_DOCDIR)+, similar to +$(FOO_PKGDIR)+, contains the path to the
directory containing +foo.mk+. It can be used to refer to the document
sources, and can be used in the hooks, especially the post-rsync hook
if parts of the documentation needs to be generated.
* +$(@D)+, as for traditional packages, contains the path to the directory
where the document will be copied and built.
Here is a complete example that uses all variables and all hooks:
----
@@ -94,8 +105,8 @@ Here is a complete example that uses all variables and all hooks:
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(FOO_DOCDIR)/ressources))
09:
10: define FOO_GEN_EXTRA_DOC
11: /path/to/generate-script --outdir=$(@D)