motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-09 10:34:58 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/devel/build-system.rst: Format literals correctly

Browse source 
In rST markup, single backticks `like this` represent "interpreted
text", which can be handled as a bunch of different things if tagged
with a specific "role":
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text
(the most common one for us is "reference to a URL, which gets
hyperlinked").

The default "role" if none is specified is "title_reference",
intended for references to book or article titles, and it renders
into the HTML as <cite>...</cite> (usually comes out as italics).

build-system.rst seems to have been written under the mistaken
assumption that single-backticks mark up literal text (function
names, etc) which should be rendered in a fixed-width font.
The rST markup for this is ``double backticks``.

Update all the markup.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20210726142338.31872-2-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell 2021-07-26 15:23:29 +01:00
parent 4e0b15c252
commit 35a4ca4031
1 changed files with 78 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

156
docs/devel/build-system.rst
View file

@ -53,14 +53,14 @@ following tasks:
- Add a Meson build option to meson_options.txt. - Add a Meson build option to meson_options.txt.
- Add support to the command line arg parser to handle any new - Add support to the command line arg parser to handle any new
`--enable-XXX`/`--disable-XXX` flags required by the feature. ``--enable-XXX``/``--disable-XXX`` flags required by the feature.
- Add information to the help output message to report on the new - Add information to the help output message to report on the new
feature flag. feature flag.
- Add code to perform the actual feature check. - Add code to perform the actual feature check.
- Add code to include the feature status in `config-host.h` - Add code to include the feature status in ``config-host.h``
- Add code to print out the feature status in the configure summary - Add code to print out the feature status in the configure summary
upon completion. upon completion.
@ -116,51 +116,51 @@ Helper functions
The configure script provides a variety of helper functions to assist The configure script provides a variety of helper functions to assist
developers in checking for system features: developers in checking for system features:
`do_cc $ARGS...` ``do_cc $ARGS...``
Attempt to run the system C compiler passing it $ARGS... Attempt to run the system C compiler passing it $ARGS...
`do_cxx $ARGS...` ``do_cxx $ARGS...``
Attempt to run the system C++ compiler passing it $ARGS... Attempt to run the system C++ compiler passing it $ARGS...
`compile_object $CFLAGS` ``compile_object $CFLAGS``
Attempt to compile a test program with the system C compiler using Attempt to compile a test program with the system C compiler using
$CFLAGS. The test program must have been previously written to a file $CFLAGS. The test program must have been previously written to a file
called $TMPC. The replacement in Meson is the compiler object `cc`, called $TMPC. The replacement in Meson is the compiler object ``cc``,
which has methods such as `cc.compiles()`, which has methods such as ``cc.compiles()``,
`cc.check_header()`, `cc.has_function()`. ``cc.check_header()``, ``cc.has_function()``.
`compile_prog $CFLAGS $LDFLAGS` ``compile_prog $CFLAGS $LDFLAGS``
Attempt to compile a test program with the system C compiler using Attempt to compile a test program with the system C compiler using
$CFLAGS and link it with the system linker using $LDFLAGS. The test $CFLAGS and link it with the system linker using $LDFLAGS. The test
program must have been previously written to a file called $TMPC. program must have been previously written to a file called $TMPC.
The replacement in Meson is `cc.find_library()` and `cc.links()`. The replacement in Meson is ``cc.find_library()`` and ``cc.links()``.
`has $COMMAND` ``has $COMMAND``
Determine if $COMMAND exists in the current environment, either as a Determine if $COMMAND exists in the current environment, either as a
shell builtin, or executable binary, returning 0 on success. The shell builtin, or executable binary, returning 0 on success. The
replacement in Meson is `find_program()`. replacement in Meson is ``find_program()``.
`check_define $NAME` ``check_define $NAME``
Determine if the macro $NAME is defined by the system C compiler Determine if the macro $NAME is defined by the system C compiler
`check_include $NAME` ``check_include $NAME``
Determine if the include $NAME file is available to the system C Determine if the include $NAME file is available to the system C
compiler. The replacement in Meson is `cc.has_header()`. compiler. The replacement in Meson is ``cc.has_header()``.
`write_c_skeleton` ``write_c_skeleton``
Write a minimal C program main() function to the temporary file Write a minimal C program main() function to the temporary file
indicated by $TMPC indicated by $TMPC
`feature_not_found $NAME $REMEDY` ``feature_not_found $NAME $REMEDY``
Print a message to stderr that the feature $NAME was not available Print a message to stderr that the feature $NAME was not available
on the system, suggesting the user try $REMEDY to address the on the system, suggesting the user try $REMEDY to address the
problem. problem.
`error_exit $MESSAGE $MORE...` ``error_exit $MESSAGE $MORE...``
Print $MESSAGE to stderr, followed by $MORE... and then exit from the Print $MESSAGE to stderr, followed by $MORE... and then exit from the
configure script with non-zero status configure script with non-zero status
`query_pkg_config $ARGS...` ``query_pkg_config $ARGS...``
Run pkg-config passing it $ARGS. If QEMU is doing a static build, Run pkg-config passing it $ARGS. If QEMU is doing a static build,
then --static will be automatically added to $ARGS then --static will be automatically added to $ARGS
@ -187,7 +187,7 @@ process for:
4) other data files, such as icons or desktop files 4) other data files, such as icons or desktop files
All executables are built by default, except for some `contrib/` All executables are built by default, except for some ``contrib/``
binaries that are known to fail to build on some platforms (for example binaries that are known to fail to build on some platforms (for example
32-bit or big-endian platforms). Tests are also built by default, 32-bit or big-endian platforms). Tests are also built by default,
though that might change in the future. though that might change in the future.
@ -195,14 +195,14 @@ though that might change in the future.
The source code is highly modularized, split across many files to The source code is highly modularized, split across many files to
facilitate building of all of these components with as little duplicated facilitate building of all of these components with as little duplicated
compilation as possible. Using the Meson "sourceset" functionality, compilation as possible. Using the Meson "sourceset" functionality,
`meson.build` files group the source files in rules that are ``meson.build`` files group the source files in rules that are
enabled according to the available system libraries and to various enabled according to the available system libraries and to various
configuration symbols. Sourcesets belong to one of four groups: configuration symbols. Sourcesets belong to one of four groups:
Subsystem sourcesets: Subsystem sourcesets:
Various subsystems that are common to both tools and emulators have Various subsystems that are common to both tools and emulators have
their own sourceset, for example `block_ss` for the block device subsystem, their own sourceset, for example ``block_ss`` for the block device subsystem,
`chardev_ss` for the character device subsystem, etc. These sourcesets ``chardev_ss`` for the character device subsystem, etc. These sourcesets
are then turned into static libraries as follows:: are then turned into static libraries as follows::
libchardev = static_library('chardev', chardev_ss.sources(), libchardev = static_library('chardev', chardev_ss.sources(),
@ -211,8 +211,8 @@ Subsystem sourcesets:
chardev = declare_dependency(link_whole: libchardev) chardev = declare_dependency(link_whole: libchardev)
As of Meson 0.55.1, the special `.fa` suffix should be used for everything As of Meson 0.55.1, the special ``.fa`` suffix should be used for everything
that is used with `link_whole`, to ensure that the link flags are placed that is used with ``link_whole``, to ensure that the link flags are placed
correctly in the command line. correctly in the command line.
Target-independent emulator sourcesets: Target-independent emulator sourcesets:
@ -221,16 +221,16 @@ Target-independent emulator sourcesets:
This includes error handling infrastructure, standard data structures, This includes error handling infrastructure, standard data structures,
platform portability wrapper functions, etc. platform portability wrapper functions, etc.
Target-independent code lives in the `common_ss`, `softmmu_ss` and Target-independent code lives in the ``common_ss``, ``softmmu_ss`` and
`user_ss` sourcesets. `common_ss` is linked into all emulators, ``user_ss`` sourcesets. ``common_ss`` is linked into all emulators,
`softmmu_ss` only in system emulators, `user_ss` only in user-mode ``softmmu_ss`` only in system emulators, ``user_ss`` only in user-mode
emulators. emulators.
Target-independent sourcesets must exercise particular care when using Target-independent sourcesets must exercise particular care when using
`if_false` rules. The `if_false` rule will be used correctly when linking ``if_false`` rules. The ``if_false`` rule will be used correctly when linking
emulator binaries; however, when *compiling* target-independent files emulator binaries; however, when *compiling* target-independent files
into .o files, Meson may need to pick *both* the `if_true` and into .o files, Meson may need to pick *both* the ``if_true`` and
`if_false` sides to cater for targets that want either side. To ``if_false`` sides to cater for targets that want either side. To
achieve that, you can add a special rule using the ``CONFIG_ALL`` achieve that, you can add a special rule using the ``CONFIG_ALL``
symbol:: symbol::
@ -245,14 +245,14 @@ Target-dependent emulator sourcesets:
In the target-dependent set lives CPU emulation, some device emulation and In the target-dependent set lives CPU emulation, some device emulation and
much glue code. This sometimes also has to be compiled multiple times, much glue code. This sometimes also has to be compiled multiple times,
once for each target being built. Target-dependent files are included once for each target being built. Target-dependent files are included
in the `specific_ss` sourceset. in the ``specific_ss`` sourceset.
Each emulator also includes sources for files in the `hw/` and `target/` Each emulator also includes sources for files in the ``hw/`` and ``target/``
subdirectories. The subdirectory used for each emulator comes subdirectories. The subdirectory used for each emulator comes
from the target's definition of ``TARGET_BASE_ARCH`` or (if missing) from the target's definition of ``TARGET_BASE_ARCH`` or (if missing)
``TARGET_ARCH``, as found in `default-configs/targets/*.mak`. ``TARGET_ARCH``, as found in ``default-configs/targets/*.mak``.
Each subdirectory in `hw/` adds one sourceset to the `hw_arch` dictionary, Each subdirectory in ``hw/`` adds one sourceset to the ``hw_arch`` dictionary,
for example:: for example::
arm_ss = ss.source_set() arm_ss = ss.source_set()
@ -262,8 +262,8 @@ Target-dependent emulator sourcesets:
The sourceset is only used for system emulators. The sourceset is only used for system emulators.
Each subdirectory in `target/` instead should add one sourceset to each Each subdirectory in ``target/`` instead should add one sourceset to each
of the `target_arch` and `target_softmmu_arch`, which are used respectively of the ``target_arch`` and ``target_softmmu_arch``, which are used respectively
for all emulators and for system emulators only. For example:: for all emulators and for system emulators only. For example::
arm_ss = ss.source_set() arm_ss = ss.source_set()
@ -273,11 +273,11 @@ Target-dependent emulator sourcesets:
target_softmmu_arch += {'arm': arm_softmmu_ss} target_softmmu_arch += {'arm': arm_softmmu_ss}
Module sourcesets: Module sourcesets:
There are two dictionaries for modules: `modules` is used for There are two dictionaries for modules: ``modules`` is used for
target-independent modules and `target_modules` is used for target-independent modules and ``target_modules`` is used for
target-dependent modules. When modules are disabled the `module` target-dependent modules. When modules are disabled the ``module``
source sets are added to `softmmu_ss` and the `target_modules` source sets are added to ``softmmu_ss`` and the ``target_modules``
source sets are added to `specific_ss`. source sets are added to ``specific_ss``.
Both dictionaries are nested. One dictionary is created per Both dictionaries are nested. One dictionary is created per
subdirectory, and these per-subdirectory dictionaries are added to subdirectory, and these per-subdirectory dictionaries are added to
@ -290,15 +290,15 @@ Module sourcesets:
modules += { 'hw-display': hw_display_modules } modules += { 'hw-display': hw_display_modules }
Utility sourcesets: Utility sourcesets:
All binaries link with a static library `libqemuutil.a`. This library All binaries link with a static library ``libqemuutil.a``. This library
is built from several sourcesets; most of them however host generated is built from several sourcesets; most of them however host generated
code, and the only two of general interest are `util_ss` and `stub_ss`. code, and the only two of general interest are ``util_ss`` and ``stub_ss``.
The separation between these two is purely for documentation purposes. The separation between these two is purely for documentation purposes.
`util_ss` contains generic utility files. Even though this code is only ``util_ss`` contains generic utility files. Even though this code is only
linked in some binaries, sometimes it requires hooks only in some of linked in some binaries, sometimes it requires hooks only in some of
these and depend on other functions that are not fully implemented by these and depend on other functions that are not fully implemented by
all QEMU binaries. `stub_ss` links dummy stubs that will only be linked all QEMU binaries. ``stub_ss`` links dummy stubs that will only be linked
into the binary if the real implementation is not present. In a way, into the binary if the real implementation is not present. In a way,
the stubs can be thought of as a portable implementation of the weak the stubs can be thought of as a portable implementation of the weak
symbols concept. symbols concept.
@ -307,8 +307,8 @@ Utility sourcesets:
The following files concur in the definition of which files are linked The following files concur in the definition of which files are linked
into each emulator: into each emulator:
`default-configs/devices/*.mak` ``default-configs/devices/*.mak``
The files under `default-configs/devices/` control the boards and devices The files under ``default-configs/devices/`` control the boards and devices
that are built into each QEMU system emulation targets. They merely contain that are built into each QEMU system emulation targets. They merely contain
a list of config variable definitions such as:: a list of config variable definitions such as::
@ -316,18 +316,18 @@ into each emulator:
CONFIG_XLNX_ZYNQMP_ARM=y CONFIG_XLNX_ZYNQMP_ARM=y
CONFIG_XLNX_VERSAL=y CONFIG_XLNX_VERSAL=y
`*/Kconfig` ``*/Kconfig``
These files are processed together with `default-configs/devices/*.mak` and These files are processed together with ``default-configs/devices/*.mak`` and
describe the dependencies between various features, subsystems and describe the dependencies between various features, subsystems and
device models. They are described in :ref:`kconfig` device models. They are described in :ref:`kconfig`
`default-configs/targets/*.mak` ``default-configs/targets/*.mak``
These files mostly define symbols that appear in the `*-config-target.h` These files mostly define symbols that appear in the ``*-config-target.h``
file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH`` file for each emulator [#cfgtarget]_. However, the ``TARGET_ARCH``
and ``TARGET_BASE_ARCH`` will also be used to select the `hw/` and and ``TARGET_BASE_ARCH`` will also be used to select the ``hw/`` and
`target/` subdirectories that are compiled into each target. ``target/`` subdirectories that are compiled into each target.
.. [#cfgtarget] This header is included by `qemu/osdep.h` when .. [#cfgtarget] This header is included by ``qemu/osdep.h`` when
compiling files from the target-specific sourcesets. compiling files from the target-specific sourcesets.
These files rarely need changing unless you are adding a completely These files rarely need changing unless you are adding a completely
@ -339,19 +339,19 @@ Support scripts
--------------- ---------------
Meson has a special convention for invoking Python scripts: if their Meson has a special convention for invoking Python scripts: if their
first line is `#! /usr/bin/env python3` and the file is *not* executable, first line is ``#! /usr/bin/env python3`` and the file is *not* executable,
find_program() arranges to invoke the script under the same Python find_program() arranges to invoke the script under the same Python
interpreter that was used to invoke Meson. This is the most common interpreter that was used to invoke Meson. This is the most common
and preferred way to invoke support scripts from Meson build files, and preferred way to invoke support scripts from Meson build files,
because it automatically uses the value of configure's --python= option. because it automatically uses the value of configure's --python= option.
In case the script is not written in Python, use a `#! /usr/bin/env ...` In case the script is not written in Python, use a ``#! /usr/bin/env ...``
line and make the script executable. line and make the script executable.
Scripts written in Python, where it is desirable to make the script Scripts written in Python, where it is desirable to make the script
executable (for example for test scripts that developers may want to executable (for example for test scripts that developers may want to
invoke from the command line, such as tests/qapi-schema/test-qapi.py), invoke from the command line, such as tests/qapi-schema/test-qapi.py),
should be invoked through the `python` variable in meson.build. For should be invoked through the ``python`` variable in meson.build. For
example:: example::
test('QAPI schema regression tests', python, test('QAPI schema regression tests', python,
@ -375,10 +375,10 @@ rules and wraps them so that e.g. submodules are built before QEMU.
The resulting build system is largely non-recursive in nature, in The resulting build system is largely non-recursive in nature, in
contrast to common practices seen with automake. contrast to common practices seen with automake.
Tests are also ran by the Makefile with the traditional `make check` Tests are also ran by the Makefile with the traditional ``make check``
phony target, while benchmarks are run with `make bench`. Meson test phony target, while benchmarks are run with ``make bench``. Meson test
suites such as `unit` can be ran with `make check-unit` too. It is also suites such as ``unit`` can be ran with ``make check-unit`` too. It is also
possible to run tests defined in meson.build with `meson test`. possible to run tests defined in meson.build with ``meson test``.
Important files for the build system Important files for the build system
==================================== ====================================
@ -390,28 +390,28 @@ The following key files are statically defined in the source tree, with
the rules needed to build QEMU. Their behaviour is influenced by a the rules needed to build QEMU. Their behaviour is influenced by a
number of dynamically created files listed later. number of dynamically created files listed later.
`Makefile` ``Makefile``
The main entry point used when invoking make to build all the components The main entry point used when invoking make to build all the components
of QEMU. The default 'all' target will naturally result in the build of of QEMU. The default 'all' target will naturally result in the build of
every component. Makefile takes care of recursively building submodules every component. Makefile takes care of recursively building submodules
directly via a non-recursive set of rules. directly via a non-recursive set of rules.
`*/meson.build` ``*/meson.build``
The meson.build file in the root directory is the main entry point for the The meson.build file in the root directory is the main entry point for the
Meson build system, and it coordinates the configuration and build of all Meson build system, and it coordinates the configuration and build of all
executables. Build rules for various subdirectories are included in executables. Build rules for various subdirectories are included in
other meson.build files spread throughout the QEMU source tree. other meson.build files spread throughout the QEMU source tree.
`tests/Makefile.include` ``tests/Makefile.include``
Rules for external test harnesses. These include the TCG tests, Rules for external test harnesses. These include the TCG tests,
`qemu-iotests` and the Avocado-based acceptance tests. ``qemu-iotests`` and the Avocado-based acceptance tests.
`tests/docker/Makefile.include` ``tests/docker/Makefile.include``
Rules for Docker tests. Like tests/Makefile, this file is included Rules for Docker tests. Like tests/Makefile, this file is included
directly by the top level Makefile, anything defined in this file will directly by the top level Makefile, anything defined in this file will
influence the entire build system. influence the entire build system.
`tests/vm/Makefile.include` ``tests/vm/Makefile.include``
Rules for VM-based tests. Like tests/Makefile, this file is included Rules for VM-based tests. Like tests/Makefile, this file is included
directly by the top level Makefile, anything defined in this file will directly by the top level Makefile, anything defined in this file will
influence the entire build system. influence the entire build system.
@ -427,11 +427,11 @@ Makefile.
Built by configure: Built by configure:
`config-host.mak` ``config-host.mak``
When configure has determined the characteristics of the build host it When configure has determined the characteristics of the build host it
will write a long list of variables to config-host.mak file. This will write a long list of variables to config-host.mak file. This
provides the various install directories, compiler / linker flags and a provides the various install directories, compiler / linker flags and a
variety of `CONFIG_*` variables related to optionally enabled features. variety of ``CONFIG_*`` variables related to optionally enabled features.
This is imported by the top level Makefile and meson.build in order to This is imported by the top level Makefile and meson.build in order to
tailor the build output. tailor the build output.
@ -446,29 +446,29 @@ Built by configure:
Built by Meson: Built by Meson:
`${TARGET-NAME}-config-devices.mak` ``${TARGET-NAME}-config-devices.mak``
TARGET-NAME is again the name of a system or userspace emulator. The TARGET-NAME is again the name of a system or userspace emulator. The
config-devices.mak file is automatically generated by make using the config-devices.mak file is automatically generated by make using the
scripts/make_device_config.sh program, feeding it the scripts/make_device_config.sh program, feeding it the
default-configs/$TARGET-NAME file as input. default-configs/$TARGET-NAME file as input.
`config-host.h`, `$TARGET-NAME/config-target.h`, `$TARGET-NAME/config-devices.h` ``config-host.h``, ``$TARGET-NAME/config-target.h``, ``$TARGET-NAME/config-devices.h``
These files are used by source code to determine what features These files are used by source code to determine what features
are enabled. They are generated from the contents of the corresponding are enabled. They are generated from the contents of the corresponding
`*.h` files using the scripts/create_config program. This extracts ``*.h`` files using the scripts/create_config program. This extracts
relevant variables and formats them as C preprocessor macros. relevant variables and formats them as C preprocessor macros.
`build.ninja` ``build.ninja``
The build rules. The build rules.
Built by Makefile: Built by Makefile:
`Makefile.ninja` ``Makefile.ninja``
A Makefile include that bridges to ninja for the actual build. The A Makefile include that bridges to ninja for the actual build. The
Makefile is mostly a list of targets that Meson included in build.ninja. Makefile is mostly a list of targets that Meson included in build.ninja.
`Makefile.mtest` ``Makefile.mtest``
The Makefile definitions that let "make check" run tests defined in The Makefile definitions that let "make check" run tests defined in
meson.build. The rules are produced from Meson's JSON description of meson.build. The rules are produced from Meson's JSON description of
tests (obtained with "meson introspect --tests") through the script tests (obtained with "meson introspect --tests") through the script
@ -478,9 +478,9 @@ Built by Makefile:
Useful make targets Useful make targets
------------------- -------------------
`help` ``help``
Print a help message for the most common build targets. Print a help message for the most common build targets.
`print-VAR` ``print-VAR``
Print the value of the variable VAR. Useful for debugging the build Print the value of the variable VAR. Useful for debugging the build
system. system.