On 17 September 2015 at 12:03, Daniel P. Berrange <berra...@redhat.com> 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 <berra...@redhat.com>
> ---
> 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
> qemu-devel@nongnu.org
> +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
> +
> + - qemu-devel@nongnu.org
> (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
