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

[Peter Maydell]

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).

> +
> +
> +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.)

> +
> +  ./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

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

> +
> +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.

> +
> +
> +Submitting patches
> +==================
> +
> +The QEMU source code is maintained under the GIT version control system.
> +
> +   git clone git://git.qemu-project.org/qemu.git
> +
> +When submitting patches, the preferred approach is to use 'git format-patch'
> +and/or 'git send-email' to format & send the mail to the address@hidden
> +mailing list. All patches submitted must contain a 'Signed-off-by' line from
> +the author.
> +
> +For additional information on submitting patches consult:
> +
> +  http://qemu-project.org/Contribute/SubmitAPatch
> +  http://qemu-project.org/Contribute/TrivialPatches
> +
> +
> +Bug reporting
> +=============
> +
> +The QEMU project uses Launchpad as its primary upstream bug tracker. Bugs
> +found when running code built from QEMU git or upstream released sources
> +should be reported via:
> +
> +  https://bugs.launchpad.net/qemu/
> +
> +If using QEMU via an operating system vendor pre-built binary package, it
> +is preferrable to report bugs to the vendor's own bug tracker first. If the

"preferable"

> +bug is also known to affect latest upstream code, it can also be reported
> +via launchpad.
> +
> +For additional information on bug reporting consult:
> +
> +  http://qemu-project.org/Contribute/ReportABug
> +
> +
> +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+).

> +  - QEMU is a trademark of Fabrice Bellard.
> +
> +For additional information on QEMU licensing consult:
> +
> +  http://qemu-project.org/License
> +
> +
> +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.

thanks
-- PMM