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

[Pierrick Bouvier <pierrick.bouvier@linaro.org>]

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