On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: > 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).
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 > > + > > + - 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. 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 :|
