35599f9a66
Recommonmark has been deprecated since 2021 [1] and the last release was
over 3 years ago [2]. As per their announcement, Markedly Structured
Text (MyST) Parser [3] is the recommended replacement.
For the most part, the existing documentation is compatible with MyST,
as both parsers are built around the CommonMark flavor of Markdown. The
main difference that affects coreboot is how the Sphinx toctree is
generated. Recommonmark has a feature called auto_toc_tree, which
converts single level lists of references into a toctree:
* [Part 1: Starting from scratch](part1.md)
* [Part 2: Submitting a patch to coreboot.org](part2.md)
* [Part 3: Writing unit tests](part3.md)
* [Managing local additions](managing_local_additions.md)
* [Flashing firmware](flashing_firmware/index.md)
MyST Parser does not provide a replacement for this feature, meaning the
toctree must be defined manually. This is done using MyST's syntax for
Sphinx directives:
```{toctree}
:maxdepth: 1
Part 1: Starting from scratch <part1.md>
Part 2: Submitting a patch to coreboot.org <part2.md>
Part 3: Writing unit tests <part3.md>
Managing local additions <managing_local_additions.md>
Flashing firmware <flashing_firmware/index.md>
```
Internally, auto_toc_tree essentially converts lists of references into
the Sphinx toctree structure that the MyST syntax above more directly
represents.
The toctrees were converted to the MyST syntax using the following
command and Python script:
`find ./ -iname "*.md" | xargs -n 1 python conv_toctree.py`
```
import re
import sys
in_list = False
f = open(sys.argv[1])
lines = f.readlines()
f.close()
with open(sys.argv[1], "w") as f:
for line in lines:
match = re.match(r"^[-*+] \[(.*)\]\((.*)\)$", line)
if match is not None:
if not in_list:
in_list = True
f.write("```{toctree}\n")
f.write(":maxdepth: 1\n\n")
f.write(match.group(1) + " <" + match.group(2) + ">\n")
else:
if in_list:
f.write("```\n")
f.write(line)
in_list = False
if in_list:
f.write("```\n")
```
While this does add a little more work for creating the toctree, this
does give more control over exactly what goes into the toctree. For
instance, lists of links to external resources currently end up in the
toctree, but we may want to limit it to pages within coreboot.
This change does break rendering and navigation of the documentation in
applications that can render Markdown, such as Okular, Gitiles, or the
GitHub mirror. Assuming the docs are mainly intended to be viewed after
being rendered to doc.coreboot.org, this is probably not an issue in
practice.
Another difference is that MyST natively supports Markdown tables,
whereas with Recommonmark, tables had to be written in embedded rST [4].
However, MyST also supports embedded rST, so the existing tables can be
easily converted as the syntax is nearly identical.
These were converted using
`find ./ -iname "*.md" | xargs -n 1 sed -i "s/eval_rst/{eval-rst}/"`
Makefile.sphinx and conf.py were regenerated from scratch by running
`sphinx-quickstart` using the updated version of Sphinx, which removes a
lot of old commented out boilerplate. Any relevant changes coreboot had
made on top of the previous autogenerated versions of these files were
ported over to the newly generated file.
From some initial testing the generated webpages appear and function
identically to the existing documentation built with Recommonmark.
TEST: `make -C util/docker docker-build-docs` builds the documentation
successfully and the generated output renders properly when viewed in
a web browser.
[1] https://github.com/readthedocs/recommonmark/issues/221
[2] https://pypi.org/project/recommonmark/
[3] https://myst-parser.readthedocs.io/en/latest/
[4] https://doc.coreboot.org/getting_started/writing_documentation.html
Change-Id: I0837c1722fa56d25c9441ea218e943d8f3d9b804
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/73158
Reviewed-by: Matt DeVillier <matt.devillier@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
4.1 KiB
The coreboot build system
(this document is still incomplete and will be filled in over time)
General operation
The coreboot build system is based on GNU make but extends it significantly to the point of providing its own custom language. The overhead of learning this new syntax is (hopefully) offset by its lower complexity.
The build system is defined in the toplevel Makefile and toolchain.mk
and is supposed to be generic (and is in fact used with a number of other
projects). Project specific configuration should reside in files called
Makefile.mk.
In general, the build system provides a number of "classes" that describe various parts of the build. These cover the various build targets in coreboot such as the stages, subdirectories with more source code, and the general addition of files.
Each class has a name (eg. romstage, subdirs, cbfs-files) and is used
by filling in a variable of that name followed by -y (eg. romstage-y,
subdirs-y, cbfs-files-y).
The -y suffix allows a simple interaction with our Kconfig build
configuration system: Kconfig options are available as variables starting
with a CONFIG_ prefix and boolean options contain y, n or are empty.
This allows class-$(CONFIG_FOO) += bar to conditionally add bar to
class depending on the choice for FOO.
classes
Classes can be defined as required. subdirs is handled internally since
it's parsed per subdirectory to add further directories to the rule set.
TODO: explain how to create new classes and how to evaluate them.
subdirs
subdirs contains subdirectories (relative to the current directory) that
should also be handled by the build system. The build system expects these
directories to contain a file called Makefile.mk.
Subdirectories are not read at the point where the subdirs statement
resides but later, after the current directory is handled (and potentially
others, too).
cbfs-files
This class is used to add files to the final CBFS image. Since several more options need to be maintained than can comfortably fit in that single variable, additional variables are used.
cbfs-files-y contains the file name used in the CBFS image (called foo
here). Additional options are added in foo-$(option) variables. The
supported options are:
file: The on-disk file to add asfoo(required)type: The file type. Can beraw,stage,payload, andflat-binary(required)compression: Can benoneorlzma(default: none)position: An absolute position constraint for the placement of the file (default: none)align: Minimum alignment for the file (default: none)options: Additional cbfstool options (default: none)
position and align are mutually exclusive.
Adding Makefile fragments
You can use the add_intermediate helper to add new post-processing steps for
the final coreboot.rom image. For example you can add new files to CBFS by
adding something like this to site-local/Makefile.mk
$(call add_intermediate, add_mrc_data)
$(CBFSTOOL) $< write -r RW_MRC_CACHE -f site-local/my-mrc-recording.bin
Note that the second line must start with a tab, not spaces.
See also :doc:`../tutorial/managing_local_additions`.
FMAP region support
With the addition of FMAP flash partitioning support to coreboot, there was a need to extend the specification of files to provide more precise control which regions should contain which files, and even change some flags based on the region.
Since FMAP policies depend on features using FMAP, that's kept separate from the cbfs-files class.
The position and align options for file foo can be overwritten for a
region REGION using foo-REGION-position and foo-REGION-align.
The regions that each file should end in can be defined by overriding a
function called regions-for-file that's called as
$(call regions-for-file,$(filename)) and should return a comma-separated
list of regions, such as REGION1,REGION2,REGION3.
The default implementation just returns COREBOOT (the default region) for
all files.
vboot provides its own implementation of regions-for-file that can be used
as reference in src/vboot/Makefile.mk.