Re: [PATCH 5/7] docs: add a codebase section

[Pierrick Bouvier]

On 12/3/24 09:46, Peter Maydell wrote:
> On Tue, 3 Dec 2024 at 17:22, Alex Bennée <alex.bennee@linaro.org> wrote:
> > Peter Maydell <peter.maydell@linaro.org> writes:
> >
> > > On Mon, 18 Nov 2024 at 17:24, Pierrick Bouvier
> > > <pierrick.bouvier@linaro.org> wrote:
> > > > Present the various parts of QEMU and organization of codebase.
> > > >
> > > > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
> > >
> > > I like this; it's something I've thought for a while would
> > > be good to have, but which I never got round to trying to
> > > put together. Thanks for doing this!
> > >
> > > Mostly my comments below are spelling/typo nits and
> > > other minor stuff.
> > >
> > > > ---
> > > >   docs/about/emulation.rst               |   2 +
> > > >   docs/codebase/index.rst                | 211 +++++++++++++++++++++++++
> > > >   docs/devel/decodetree.rst              |   2 +
> > > >   docs/devel/ebpf_rss.rst                |   2 +
> > > >   docs/devel/index-internals.rst         |   2 +
> > > >   docs/devel/migration/main.rst          |   2 +
> > > >   docs/devel/qapi-code-gen.rst           |   1 +
> > > >   docs/devel/testing/main.rst            |   9 +-
> > > >   docs/devel/testing/qtest.rst           |   2 +
> > > >   docs/index.rst                         |   3 +
> > > >   docs/interop/qemu-ga.rst               |   2 +
> > > >   docs/system/qemu-block-drivers.rst.inc |   2 +
> > > >   docs/tools/qemu-storage-daemon.rst     |   2 +
> > > >   docs/user/main.rst                     |   6 +
> > > >   14 files changed, 247 insertions(+), 1 deletion(-)
> > > >   create mode 100644 docs/codebase/index.rst
> > <snip>
> > > > +  Block devices and `image formats<disk images>` implementation.
> > > > +* `bsd-user <https://gitlab.com/qemu-project/qemu/-/tree/master/bsd-user>`_:
> > > > +  `BSD User mode<bsd-user-mode>`.
> > > > +* build: Where the code built goes!
> > >
> > > The built code doesn't have to be in 'build'. We could say:
> > >
> > >   * build: You can tell the QEMU build system to put the built code
> > >     anywhere you like. By default it will go into a directory named
> > >     ``build``. Sometimes documentation will assume this default
> > >     for convenience when describing command lines; you can always
> > >     replace it with the path to your build tree.
> > >
> > > ?
> >
> > I always recommend creating a builds directory and having multiple build
> > trees under it:
>
> Indeed, that's what I like to do too, but I don't think this
> document is the right place to make that kind of recommendation.

I agree with Peter.
People who understand this need already know how to do it, and it's not 
the best place to mention that.

As well, using several folders can be error prone (using "old" binaries 
by mistake happens quickly), and it's something I usually don't advise 
for beginners. Using a symlink that points to the right folder is less 
error prone, but it opens the path to another (custom and personal) 
layer to the build command.

Another (more simple) solution is to use a single folder, and simply 
rely on ccache for quick rebuilds.

There are probably as many solutions and opinions as there are 
developers on this thread, so it's better to simply mention one build 
folder, and nothing else.

> -- PMM