[7/7] docs: add a how to section

Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
---
 docs/devel/build-system.rst |   2 +
 docs/how-to/index.rst       | 146 ++++++++++++++++++++++++++++++++++++
 docs/index.rst              |   1 +
 3 files changed, 149 insertions(+)
 create mode 100644 docs/how-to/index.rst

On Mon, Nov 18, 2024 at 09:23:57AM -0800, Pierrick Bouvier wrote:
> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> ---
>  docs/devel/build-system.rst |   2 +
>  docs/how-to/index.rst       | 146 ++++++++++++++++++++++++++++++++++++
>  docs/index.rst              |   1 +
>  3 files changed, 149 insertions(+)
>  create mode 100644 docs/how-to/index.rst
> 
> diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
> index d42045a2325..db444787e37 100644
> --- a/docs/devel/build-system.rst
> +++ b/docs/devel/build-system.rst
> @@ -1,3 +1,5 @@
> +.. _build:
> +
>  ==================================
>  The QEMU build system architecture
>  ==================================
> diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
> new file mode 100644
> index 00000000000..3a9d4d777df
> --- /dev/null
> +++ b/docs/how-to/index.rst
> @@ -0,0 +1,146 @@
> +.. _how-to:
> +
> +------
> +How to
> +------
> +
> +This section of the manual will give you some commands to do various tasks with
> +QEMU. It does not intend to be complete, but to be simple.
> +
> +Build
> +-----
> +
> +First you need setup your `build environment <setup-build-env>`.
> +
> +Then, you can build QEMU using:
> +
> +::
> +
> +    git clone https://gitlab.com/qemu-project/qemu
> +    cd qemu
> +    ./configure
> +    ninja -C build
> +    # all binaries are in ./build
> +
> +By default, QEMU build is optimized. You may want to switch to debug builds
> +instead (non optimized, and with more runtime checks enabled):
> +
> +::
> +
> +    ./configure --enable-debug
> +
> +It's recommended to use sanitizers to catch issues when developing your change.
> +
> +::
> +
> +    ./configure --enable-asan --enable-ubsan
> +    # Of course, you can combine debug and sanitizers if needed
> +
> +You can find more information on `build page <build>`.
> +
> +Test
> +----
> +
> +QEMU has a lot of tests, mainly in 4 categories:
> +
> +::
> +
> +    # run tests related to TCG. They are based on Makefiles.
> +    make check-tcg
> +    # run system tests, running a full VM, with avocado framework
> +    make check-avocado
> +    # run functional tests, running a full VM, integrated with Meson
> +    make check-functional
> +    # run all other tests, integrated with Meson
> +    make check
> +
> +You can find more information on `testing page<testing>`.
> +
> +Use QEMU
> +--------
> +
> +To create a 20 gigabytes disk image usable with qemu-system:
> +
> +::
> +
> +    qemu-img create system.img 20g
> +
> +To run an x86_64 system emulated, with 4 cpus, 8G of memory and an install iso:
> +
> +::
> +
> +    qemu-system-x86_64 -smp 4 -m 8G system.img -cdrom install.iso
> +
> +To boot directly a Linux Kernel:
> +
> +::
> +
> +    qemu-system-x86_64 -kernel bzImage -hda system.img -append "root=/dev/hda"
> +
> +To boot an aarch64 system emulated, you need to specify a UEFI and associated
> +pflash. Once started, you can switch to Serial output by clicking on View ->
> +Serial0.
> +
> +::
> +
> +    # UEFI can be obtained from debian package qemu-efi-aarch64.
> +    # First, we need to copy a file to save UEFI variables:
> +    # cp /usr/share/AAVMF/AAVMF_VARS.fd .
> +    qemu-system-aarch64 \
> +        -m 8G \
> +        -smp 4 \
> +        -M virt \
> +        -cpu max \
> +        -device virtio-blk-pci,drive=root \
> +        -drive if=none,id=root,file=system.img \
> +        -drive if=pflash,readonly=on,file=/usr/share/AAVMF/AAVMF_CODE.fd \
> +        -drive if=pflash,file=AAVMF_VARS.fd \
> +        -cdrom install.iso
> +
> +To run git using QEMU user-mode:
> +
> +::
> +
> +    qemu-x86_64 /usr/bin/git --version
> +
> +Contribute
> +----------
> +
> +We recommend using `git-publish <https://github.com/stefanha/git-publish>`_ for
> +contributing. You need to configure `git send-email
> +<https://git-send-email.io/>`_ first.
> +
> +::
> +
> +    git checkout -b my_feature
> +    ... # edit, build, test
> +    # When ready to send the series...
> +
> +    # Add upstream QEMU repo as a remote.
> +    git remote add upstream https://gitlab.com/qemu-project/qemu
> +    # Fetch all new content.
> +    git fetch -a upstream
> +
> +    # Rebase your branch on top of upstream master, and include a signoff.
> +    git rebase -i upstream/master --signoff
> +    # Check your patches are correct.
> +    ./scripts/checkpatch.pl $(git merge-base upstream/master HEAD)..HEAD
> +
> +    # Send your series, you'll be given a chance to edit cover letter for it.
> +    git-publish
> +
> +    # After review, and other changes, you can send a v2 simply by using:
> +    git-publish
> +
> +If you need to apply locally an existing series, you can use `b4
> +<https://github.com/mricon/b4>`_ (installable via pip) to retrieve it:
> +
> +::
> +
> +    b4 shazam <series_msg_id>
> +    # message id is an identifier present in email sent.
> +    # when using patchwork, it is the last part of a series url (2024...):
> +    # https://patchew.org/QEMU/20241118021820.4928-1-joel@jms.id.au/
> +
> +More complete information is available on our `Submit a patch page
> +<submitting-a-patch>`.

I'm far from convinced any of the above content is a good idea, given
it is duplicating stuff we've already got elsewhere in our manual.
This gives us the extra burden of ensuring different parts of the
manual are consistent in what they're recommending which is something
we are historically bad at doing.

I think there is scope for having a "how-tos" section, but this particular
choices of examples are not the best place to kick it off with IMHO. Also,
for the sake of scalability, I'd suggest that each "how to" is a standalone
file in the how-tos/ sub-directory, otherwise the index.rst will quickly
become enourmous.

With regards,
Daniel

On 11/19/24 01:29, Daniel P. Berrangé wrote:
> On Mon, Nov 18, 2024 at 09:23:57AM -0800, Pierrick Bouvier wrote:
>> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
>> ---
>>   docs/devel/build-system.rst |   2 +
>>   docs/how-to/index.rst       | 146 ++++++++++++++++++++++++++++++++++++
>>   docs/index.rst              |   1 +
>>   3 files changed, 149 insertions(+)
>>   create mode 100644 docs/how-to/index.rst
>>
>> diff --git a/docs/devel/build-system.rst b/docs/devel/build-system.rst
>> index d42045a2325..db444787e37 100644
>> --- a/docs/devel/build-system.rst
>> +++ b/docs/devel/build-system.rst
>> @@ -1,3 +1,5 @@
>> +.. _build:
>> +
>>   ==================================
>>   The QEMU build system architecture
>>   ==================================
>> diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
>> new file mode 100644
>> index 00000000000..3a9d4d777df
>> --- /dev/null
>> +++ b/docs/how-to/index.rst
>> @@ -0,0 +1,146 @@
>> +.. _how-to:
>> +
>> +------
>> +How to
>> +------
>> +
>> +This section of the manual will give you some commands to do various tasks with
>> +QEMU. It does not intend to be complete, but to be simple.
>> +
>> +Build
>> +-----
>> +
>> +First you need setup your `build environment <setup-build-env>`.
>> +
>> +Then, you can build QEMU using:
>> +
>> +::
>> +
>> +    git clone https://gitlab.com/qemu-project/qemu
>> +    cd qemu
>> +    ./configure
>> +    ninja -C build
>> +    # all binaries are in ./build
>> +
>> +By default, QEMU build is optimized. You may want to switch to debug builds
>> +instead (non optimized, and with more runtime checks enabled):
>> +
>> +::
>> +
>> +    ./configure --enable-debug
>> +
>> +It's recommended to use sanitizers to catch issues when developing your change.
>> +
>> +::
>> +
>> +    ./configure --enable-asan --enable-ubsan
>> +    # Of course, you can combine debug and sanitizers if needed
>> +
>> +You can find more information on `build page <build>`.
>> +
>> +Test
>> +----
>> +
>> +QEMU has a lot of tests, mainly in 4 categories:
>> +
>> +::
>> +
>> +    # run tests related to TCG. They are based on Makefiles.
>> +    make check-tcg
>> +    # run system tests, running a full VM, with avocado framework
>> +    make check-avocado
>> +    # run functional tests, running a full VM, integrated with Meson
>> +    make check-functional
>> +    # run all other tests, integrated with Meson
>> +    make check
>> +
>> +You can find more information on `testing page<testing>`.
>> +
>> +Use QEMU
>> +--------
>> +
>> +To create a 20 gigabytes disk image usable with qemu-system:
>> +
>> +::
>> +
>> +    qemu-img create system.img 20g
>> +
>> +To run an x86_64 system emulated, with 4 cpus, 8G of memory and an install iso:
>> +
>> +::
>> +
>> +    qemu-system-x86_64 -smp 4 -m 8G system.img -cdrom install.iso
>> +
>> +To boot directly a Linux Kernel:
>> +
>> +::
>> +
>> +    qemu-system-x86_64 -kernel bzImage -hda system.img -append "root=/dev/hda"
>> +
>> +To boot an aarch64 system emulated, you need to specify a UEFI and associated
>> +pflash. Once started, you can switch to Serial output by clicking on View ->
>> +Serial0.
>> +
>> +::
>> +
>> +    # UEFI can be obtained from debian package qemu-efi-aarch64.
>> +    # First, we need to copy a file to save UEFI variables:
>> +    # cp /usr/share/AAVMF/AAVMF_VARS.fd .
>> +    qemu-system-aarch64 \
>> +        -m 8G \
>> +        -smp 4 \
>> +        -M virt \
>> +        -cpu max \
>> +        -device virtio-blk-pci,drive=root \
>> +        -drive if=none,id=root,file=system.img \
>> +        -drive if=pflash,readonly=on,file=/usr/share/AAVMF/AAVMF_CODE.fd \
>> +        -drive if=pflash,file=AAVMF_VARS.fd \
>> +        -cdrom install.iso
>> +
>> +To run git using QEMU user-mode:
>> +
>> +::
>> +
>> +    qemu-x86_64 /usr/bin/git --version
>> +
>> +Contribute
>> +----------
>> +
>> +We recommend using `git-publish <https://github.com/stefanha/git-publish>`_ for
>> +contributing. You need to configure `git send-email
>> +<https://git-send-email.io/>`_ first.
>> +
>> +::
>> +
>> +    git checkout -b my_feature
>> +    ... # edit, build, test
>> +    # When ready to send the series...
>> +
>> +    # Add upstream QEMU repo as a remote.
>> +    git remote add upstream https://gitlab.com/qemu-project/qemu
>> +    # Fetch all new content.
>> +    git fetch -a upstream
>> +
>> +    # Rebase your branch on top of upstream master, and include a signoff.
>> +    git rebase -i upstream/master --signoff
>> +    # Check your patches are correct.
>> +    ./scripts/checkpatch.pl $(git merge-base upstream/master HEAD)..HEAD
>> +
>> +    # Send your series, you'll be given a chance to edit cover letter for it.
>> +    git-publish
>> +
>> +    # After review, and other changes, you can send a v2 simply by using:
>> +    git-publish
>> +
>> +If you need to apply locally an existing series, you can use `b4
>> +<https://github.com/mricon/b4>`_ (installable via pip) to retrieve it:
>> +
>> +::
>> +
>> +    b4 shazam <series_msg_id>
>> +    # message id is an identifier present in email sent.
>> +    # when using patchwork, it is the last part of a series url (2024...):
>> +    # https://patchew.org/QEMU/20241118021820.4928-1-joel@jms.id.au/
>> +
>> +More complete information is available on our `Submit a patch page
>> +<submitting-a-patch>`.
> 
> I'm far from convinced any of the above content is a good idea, given
> it is duplicating stuff we've already got elsewhere in our manual.
> This gives us the extra burden of ensuring different parts of the
> manual are consistent in what they're recommending which is something
> we are historically bad at doing.
> 

My idea was to keep this whole together instead of scattering those 
"basic" use cases across all the documentation, which makes them hard to 
find by design.

> I think there is scope for having a "how-tos" section, but this particular
> choices of examples are not the best place to kick it off with IMHO. Also,
> for the sake of scalability, I'd suggest that each "how to" is a standalone
> file in the how-tos/ sub-directory, otherwise the index.rst will quickly
> become enourmous.
> 

I will leave that page out of this series, if you feel it's not a good 
approach for now.
In case we revisit the idea later, I think the how-to section should 
*not* become a huge wiki page, where all the niche use cases we imagine 
are documented, but simply a way for new developers to do the basic 
operations (build/execute/test/contribute) they need. That's the 
compromise I tried to create here, based on my personal experience as a 
new developer on QEMU.

> With regards,
> Daniel