Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information

[Daniel P. Berrange]

On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote:
> On 17 September 2015 at 12:03, Daniel P. Berrange <address@hidden> wrote:
> > The README file is usually the first thing consulted when a user
> > or developer obtains a copy of the QEMU source. The current QEMU
> > README is lacking immediately useful information and so not very
> > friendly for first time encounters. It either redirects users to
> > qemu-doc.html (which does not exist until they've actually
> > compiled QEMU), or the website (which assumes the user has
> > convenient internet access at time of reading).
> >
> > This fills out the README file as simple quick-start guide on
> > the topics of building source, submitting patches, licensing
> > and how to contact the QEMU community. It does not intend to be
> > comprehensive, instead referring people to an appropriate web
> > page to obtain more detailed information. The intent is to give
> > users quick guidance to get them going in the right direction.
> >
> > Signed-off-by: Daniel P. Berrange <address@hidden>
> > ---
> >  README | 108 
> > +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
> >  1 file changed, 106 insertions(+), 2 deletions(-)
> >
> > diff --git a/README b/README
> > index c7c990d..71142c3 100644
> > --- a/README
> > +++ b/README
> > @@ -1,3 +1,107 @@
> > -Read the documentation in qemu-doc.html or on http://wiki.qemu-project.org
> > +         QEMU README
> > +        ===========
> >
> > -- QEMU team
> > +QEMU is a generic and open source machine emulator and virtualizer. When 
> > used
> > +as a machine emulator, QEMU can run OSes and programs made for one machine
> > +(e.g. an ARM board) on a different machine (e.g. your own PC). By using 
> > dynamic
> > +translation, it achieves very good performance. When used as a virtualizer,
> > +QEMU achieves near native performances by executing the guest code 
> > directly on
> > +the host CPU. QEMU supports virtualization when executing under the Xen
> > +hypervisor or using the KVM kernel module in Linux.
> 
> This kind of forgets the linux-user use case (which isn't machine emulation).

FYI, I just copied this text from the qemu-project.org front page :-) If
anyone has suggestions for improvements I'm all ears - we should update
the website too.

> > +Building
> > +========
> > +
> > +QEMU is multi-platform software intended to be buildable on all modern 
> > Linux
> > +platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other
> > +UNIX targets. The simple process to build QEMU is
> 
> This whole section seems to be duplicating our existing build
> documentation (which is in qemu-doc.texi in the 'compilation'
> section). We should document how to build QEMU in exactly one
> place, not two (though I can see the rationale for that one
> place not being in a .texi file.)

The problem I have with refering people to qemu-doc.html,
is that in order to order to view the docs on how to build
QEMU, you first have to build QEMU, or enjoy reading the
.texi source code :-)  Though that doc does get exposed
via the website too, it is nice to not rely on people having
internet access all the time.

The qemu-doc.html chapter 6 is a bit more detailed in what
it descibes. I tend to view the instructions we put in the
README file as the minimal quick-start, and then point to
the comprehensive docs as a detailed reference on the matter.

> > +  ./configure
> > +  make
> > +  sudo make install
> 
> I would prefer it if we recommended people to build in a separate
> build directory, ie:
> 
>     mkdir build
>     cd build
>     ../configure
>     make

Sure, that does make sense.

> 
> Also I'm not sure our 'make install' target is a great thing to recommend.

Any particular reason why 'make install' is bad ? I've not personally
had any trouble with it, though to be fair I always build with
'--prefix=$HOME/usr/qemu-git' so I'm not splattering stuff into /usr

> 
> > +
> > +The configure script supports a number of arguments to turn on/off various
> > +optional features. These can be seen with "configure --help".
> > +
> > +For additional information on building QEMU for Linux and Windows consult:
> > +
> > +  http://qemu-project.org/Hosts/Linux
> > +  http://qemu-project.org/Hosts/W32
> 
> We've just significantly improved our documentation for building
> on OSX, and we should mention it here.

Are those docs mentioned anywhere on the wiki, or just in the qemu-doc.html
file ?  I took these two links from this page:

  http://qemu-project.org/Documentation/GettingStartedDevelopers

which doesn't mention OS-X. So we should probably address that at the
same time.

> > +Licensing
> > +=========
> 
> This section seems to be duplicating the LICENSE file.
> 
> > +
> > +  - QEMU as a whole is released under the GNU General Public License, 
> > version 2.
> > +
> > +  - Parts of QEMU have specific licenses which are compatible with the GNU
> > +    General Public License, version 2. Hence each source file contains its 
> > own
> > +    licensing information. Source files with no licensing information are
> > +    released under the GNU General Public License, version 2 or (at your
> > +    option) any later version. As of July 2013, contributions under version
> > +    2 of the GNU General Public License (and no later version) are only
> > +    accepted for the following files or directories: bsd-user/, 
> > linux-user/,
> > +    hw/misc/vfio.c, hw/xen/xen_pt*.
> > +
> > +  - The Tiny Code Generator (TCG) is released under the BSD license (see
> > +    license headers in files).
> 
> This part is no longer entirely true, incidentally (eg the AArch64 TCG backend
> is GPL2+).

I can just do what Paolo suggests and simply point people to the LICENSE
file instead.

> > +Contact
> > +=======
> > +
> > +The QEMU community can be contacted in a number of ways, with the two main
> > +methods being E-Mail and IRC
> > +
> > + - address@hidden (http://lists.nongnu.org/mailman/listinfo/qemu-devel)
> > + - #qemu on irc.oftc.net
> > +
> > +For additional information on contacted the community consult:
> > +
> > +  http://qemu-project.org/Contribute/StartHere
> > +
> > +-- End
> 
> Some of the lines in this file seem to be a bit over-long.

Any preference for max length to stick too ? I merely ran
it through checkpatch.pl, which enforces 80 char limit IIRC.
I'm happy to reformat to shorter a shorter length if desired.

Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|