| Message ID | 1442487809-2403-1-git-send-email-berrange@redhat.com |
|---|---|
| State | New |
| Headers | show |
On 17 September 2015 at 12:03, Daniel P. Berrange <berrange@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 <berrange@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
On 17/09/2015 13:03, Daniel P. Berrange wrote: > + > +Licensing > +========= > + > + - 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). > + > + - QEMU is a trademark of Fabrice Bellard. > + > +For additional information on QEMU licensing consult: > + > + http://qemu-project.org/License As mentioned by Peter, this text and this URL are a duplicate of the LICENSE file. I would just put a tl;dr in the README file, like this: 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. For additional information on QEMU licensing see the LICENSE file. Paolo
On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: > On 17 September 2015 at 12:03, Daniel P. Berrange <berrange@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 <berrange@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
On 17 September 2015 at 13:05, Daniel P. Berrange <berrange@redhat.com> wrote: > On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: >> On 17 September 2015 at 12:03, Daniel P. Berrange <berrange@redhat.com> wrote: > >> > +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. I don't think we should have two places at all. If a "quick start" is useful it should be at the start of the one document we have on building QEMU. >> 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 Pretty much the "splats over /usr", with a side order of "I'm not sure how much testing it gets". >> > + >> > +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. The OSX documentation is in qemu-doc.texi. Again, we should have all our 'how to build' docs in one place. >> 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. Yes, that would be better. >> > +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. Wrap-at-between-70-and-75-ish is the usual recommendation, I think. thanks -- PMM
On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote: > On 17 September 2015 at 13:05, Daniel P. Berrange <berrange@redhat.com> wrote: > > On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: > >> On 17 September 2015 at 12:03, Daniel P. Berrange <berrange@redhat.com> wrote: > > > >> > +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. > > I don't think we should have two places at all. If a "quick > start" is useful it should be at the start of the one document > we have on building QEMU. How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi file into a standalone file, in a format that is friendly to read without needing generating first. Perhaps using something like Markdown[1] would be a suitable thing, as that is essentially plain text with a little extra punctuation, so it is easily readable as source, as well as allowing reasonably pleasant HTML generation allowing us to publish it to the website too ? > >> 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 > > Pretty much the "splats over /usr", with a side order of "I'm not > sure how much testing it gets". Heh, ok Regards, Daniel [1] eg https://help.github.com/articles/markdown-basics/ http://daringfireball.net/projects/markdown/syntax
On 17 September 2015 at 13:36, Daniel P. Berrange <berrange@redhat.com> wrote: > How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi > file into a standalone file, in a format that is friendly to read > without needing generating first. Perhaps using something like > Markdown[1] would be a suitable thing, as that is essentially plain > text with a little extra punctuation, so it is easily readable as > source, as well as allowing reasonably pleasant HTML generation > allowing us to publish it to the website too ? Yes, that sounds like a good idea. -- PMM
"Daniel P. Berrange" <berrange@redhat.com> writes: > On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote: >> On 17 September 2015 at 13:05, Daniel P. Berrange <berrange@redhat.com> wrote: >> > On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: >> >> On 17 September 2015 at 12:03, Daniel P. Berrange >> >> <berrange@redhat.com> wrote: >> > >> >> > +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. >> >> I don't think we should have two places at all. If a "quick >> start" is useful it should be at the start of the one document >> we have on building QEMU. > > How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi > file into a standalone file, in a format that is friendly to read > without needing generating first. Do we want a "Compilation" chapter in qemu-doc, or do we want it to be a separate document? "Both" is a legitimate answer. Multiple documents can be generated from a single source. Must the separate document be available right after unpacking a tarball? "Yes" doesn't mean we can't generate it --- projects include generated files in tarballs all the time, e.g. Autoconf-generated configure. Must the separate document be available right after git-clone? "Yes" doesn't mean we can't generate it, only that we have to commit a generated file, which is a bit awkward. Personally, I wouldn't bother. People capable of git-clone are capable of finding and running a bootstrap script. Common with projects using Autoconf that don't commit the generated configure. > Perhaps using something like > Markdown[1] would be a suitable thing, as that is essentially plain > text with a little extra punctuation, so it is easily readable as > source, as well as allowing reasonably pleasant HTML generation > allowing us to publish it to the website too ? Texinfo isn't exactly the greatest markup system, but it works, and it can generate reasonably pleasant HTML. Ditto PDF and plain text. Why not extract the existing chapter into a separate .texi, include it from the user manual, include it from a trivial .texi master file, format the latter to plain text with something like $ texi2any --plaintext -I . how-to-build.texi >HOW-TO-BUILD No need for redoing the markup. [...]
On 09/17/2015 07:03 AM, Daniel P. Berrange 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 <berrange@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. > + > + > +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 > + > + ./configure > + make > + sudo make install > + > +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 > + > + > +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 > + I'd mention the HACKING and CODING_STYLE files too, since they're likely to be in the same folder as this README, which relates back to your "useful offline" point in the commit message justification. > + > +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, in US English at least. (As an aside: are we formalized on en_US or en_GB? neither?) > +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 > +========= > + > + - 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). > + > + - QEMU is a trademark of Fabrice Bellard. > + > +For additional information on QEMU licensing consult: > + I think this and other uses could tolerate a comma. "For additional information on QEMU licensing, consult: " > + http://qemu-project.org/License > + I would make clear that this is a licensing brief/summary and not the actual authoritative text by which the project is licensed under the GPL; again I would direct people to look at ./LICENSE and ./COPYING as the authorities on the matter. > + > +Contact > +======= > + > +The QEMU community can be contacted in a number of ways, with the two main > +methods being E-Mail and IRC > + Grammar bikeshedding: "E-Mail" is absurdly formal. The common usage is lower-cased "email." > + - 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: > + huh? I think: "For additional information on [methods of] contacting the community, consult:" > + http://qemu-project.org/Contribute/StartHere > + > +-- End > As a random aside, it'd be nice to have a quick 101 somewhere obvious that helps explain to users what QEMU's role in the ecosystem is. For instance, the boundary between KVM, QEMU and libvirt seems to be misunderstood frequently by first-time users and even contributors. We touch on the qemu-kvm interaction in the first paragraph, but for people even less familiar with the territory, a simplified explanation might help: "QEMU is capable of emulating a complete machine in software without any need for hardware virtualization support. With the addition of Xen or KVM on supported hardware platforms (e.g. x86's VT-x), QEMU can be configured to emulate only the hardware and allows the hypervisor to manage CPU and APIC emulation. In common usage, QEMU behaves as the computer hardware while e.g. KVM behaves as the CPU." I'm sure my summary here is not resoundingly correct on all levels of the metaphor, but it's roughly correct -- and someone with a better technical mind than I should write a little disambiguation blurb about what exactly the line between qemu+kvm is. I think it would help clear up some things for some people. And of course, further explaining the role of e.g. libvirt and virt-manager may help get users up to speed on the norms for how the project is used. "QEMU is intended as a component in a full virtualization solution and as-such does not provide robust or comprehensive UI solutions or interfaces. QEMU does instead provide a robust and stable API for use by management frameworks such as libvirt, which are used to build external management applications such as virtual machine manager." $0.02. --js
On 09/17/2015 12:43 PM, Markus Armbruster wrote: > "Daniel P. Berrange" <berrange@redhat.com> writes: > >> On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote: >>> On 17 September 2015 at 13:05, Daniel P. Berrange <berrange@redhat.com> wrote: >>>> On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: >>>>> On 17 September 2015 at 12:03, Daniel P. Berrange >>>>> <berrange@redhat.com> wrote: >>>> >>>>>> +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. >>> >>> I don't think we should have two places at all. If a "quick >>> start" is useful it should be at the start of the one document >>> we have on building QEMU. >> >> How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi >> file into a standalone file, in a format that is friendly to read >> without needing generating first. > > Do we want a "Compilation" chapter in qemu-doc, or do we want it to be a > separate document? "Both" is a legitimate answer. Multiple documents > can be generated from a single source. > > Must the separate document be available right after unpacking a tarball? > "Yes" doesn't mean we can't generate it --- projects include generated > files in tarballs all the time, e.g. Autoconf-generated configure. > > Must the separate document be available right after git-clone? "Yes" > doesn't mean we can't generate it, only that we have to commit a > generated file, which is a bit awkward. > > Personally, I wouldn't bother. People capable of git-clone are capable > of finding and running a bootstrap script. Common with projects using > Autoconf that don't commit the generated configure. > OK, but I'd spell it out: "To build QEMU, you'd generally [some basic steps that have generally worked for a long time], but for up-to-date authoritative information, please do: mkdir path_to/build_dir cd path_to/build_dir ../../configure make qemu-doc.html" We wind up documenting how to almost do a build anyway. So I think we'd need to make the qemu-doc file one we can generate without needing to get through the sometimes-arduous configure step first. Or at least, split out the build information into something that can be generated in a standalone fashion. My personal preference is, like in my above example, to give a brief "Here's what usually works" blurb as a quick-start that will hopefully work for most people, followed by a link to a more authoritative document that takes more mental energy to parse (or even to conjure into existence) than the quick blurb. At this point though, we're already being a huge pain in the ass. I'm in favor of a statically available "Here's how to build" that we don't need to generate, but I won't insist on it if there are some strong reasons that we need to auto-generate simple build information. --js >> Perhaps using something like >> Markdown[1] would be a suitable thing, as that is essentially plain >> text with a little extra punctuation, so it is easily readable as >> source, as well as allowing reasonably pleasant HTML generation >> allowing us to publish it to the website too ? > > Texinfo isn't exactly the greatest markup system, but it works, and it > can generate reasonably pleasant HTML. Ditto PDF and plain text. > > Why not extract the existing chapter into a separate .texi, include it > from the user manual, include it from a trivial .texi master file, > format the latter to plain text with something like > > $ texi2any --plaintext -I . how-to-build.texi >HOW-TO-BUILD > > No need for redoing the markup. > > [...] >
John Snow <jsnow@redhat.com> writes: > On 09/17/2015 12:43 PM, Markus Armbruster wrote: >> "Daniel P. Berrange" <berrange@redhat.com> writes: >> >>> On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote: >>>> On 17 September 2015 at 13:05, Daniel P. Berrange >>>> <berrange@redhat.com> wrote: >>>>> On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: >>>>>> On 17 September 2015 at 12:03, Daniel P. Berrange >>>>>> <berrange@redhat.com> wrote: >>>>> >>>>>>> +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. >>>> >>>> I don't think we should have two places at all. If a "quick >>>> start" is useful it should be at the start of the one document >>>> we have on building QEMU. >>> >>> How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi >>> file into a standalone file, in a format that is friendly to read >>> without needing generating first. >> >> Do we want a "Compilation" chapter in qemu-doc, or do we want it to be a >> separate document? "Both" is a legitimate answer. Multiple documents >> can be generated from a single source. >> >> Must the separate document be available right after unpacking a tarball? >> "Yes" doesn't mean we can't generate it --- projects include generated >> files in tarballs all the time, e.g. Autoconf-generated configure. >> >> Must the separate document be available right after git-clone? "Yes" >> doesn't mean we can't generate it, only that we have to commit a >> generated file, which is a bit awkward. >> >> Personally, I wouldn't bother. People capable of git-clone are capable >> of finding and running a bootstrap script. Common with projects using >> Autoconf that don't commit the generated configure. >> > > OK, but I'd spell it out: > > "To build QEMU, you'd generally [some basic steps that have generally > worked for a long time], but for up-to-date authoritative information, > please do: > > mkdir path_to/build_dir > cd path_to/build_dir > ../../configure > make qemu-doc.html" > > We wind up documenting how to almost do a build anyway. If we follow the customary way projects using Autoconf avoid committing generated stuff, this would be as simple as: If you build from a tarball: 1. Unpack the tarball. Since you're reading this, you probably did that already. 2. cd to the root of the source tree. 3. Read [insert filename] for further instructions. If you build from git: 1. Clone the tree. Since you're reading this, you probably did that already. 2. cd to the root of the source tree and run "./bootstrap". This requires [insert prereqs...] to be installed. 3. Read [insert filename] for further instructions. The git version of step 2 generates the file for step 3 from sources. It's included in the tarball. > So I think we'd need to make the qemu-doc file one we can generate > without needing to get through the sometimes-arduous configure step first. > > Or at least, split out the build information into something that can be > generated in a standalone fashion. > > My personal preference is, like in my above example, to give a brief > "Here's what usually works" blurb as a quick-start that will hopefully > work for most people, followed by a link to a more authoritative > document that takes more mental energy to parse (or even to conjure into > existence) than the quick blurb. > > At this point though, we're already being a huge pain in the ass. I'm in > favor of a statically available "Here's how to build" that we don't need > to generate, but I won't insist on it if there are some strong reasons > that we need to auto-generate simple build information. I honestly don't think the three steps above qualify as painful.
On 22/09/2015 10:16, Markus Armbruster wrote: >> "To build QEMU, you'd generally [some basic steps that have generally >> worked for a long time], but for up-to-date authoritative information, >> please do: >> >> mkdir path_to/build_dir >> cd path_to/build_dir >> ../../configure >> make qemu-doc.html" >> >> We wind up documenting how to almost do a build anyway. I don't think this is necessary. We should remove duplicate information from qemu-doc.texi, developer documentation doesn't belong in manuals. Paolo
Paolo Bonzini <pbonzini@redhat.com> writes: > On 22/09/2015 10:16, Markus Armbruster wrote: > >> John Snow <jsnow@redhat.com> writes: >> >>> "To build QEMU, you'd generally [some basic steps that have generally >>> worked for a long time], but for up-to-date authoritative information, >>> please do: >>> >>> mkdir path_to/build_dir >>> cd path_to/build_dir >>> ../../configure >>> make qemu-doc.html" >>> >>> We wind up documenting how to almost do a build anyway. > > I don't think this is necessary. We should remove duplicate information > from qemu-doc.texi, developer documentation doesn't belong in manuals. Just to avoid misunderstandings: I wouldn't object to splitting qemu-doc.texi into a user manual and developer documentation.
On 23/09/2015 11:52, Markus Armbruster wrote: > > I don't think this is necessary. We should remove duplicate information > > from qemu-doc.texi, developer documentation doesn't belong in manuals. > > Just to avoid misunderstandings: I wouldn't object to splitting > qemu-doc.texi into a user manual and developer documentation. That really boils down to moving chapter 6 somewhere else; everything else is user documentation. I think we should start with Dan's patch, and then integrate it with any missing information from chapter 6. Together with his build system docs, the non-texi developer documentation is better than anything qemu-doc.texi has ever had (*insert usual rant about perfect being the enemy of good*). We also have the opposite problem (user documentation placed in docs/ instead of qemu-doc.texi) but that is separate. Paolo
On Wed, Sep 23, 2015 at 12:00:08PM +0200, Paolo Bonzini wrote: > > > On 23/09/2015 11:52, Markus Armbruster wrote: > > > I don't think this is necessary. We should remove duplicate information > > > from qemu-doc.texi, developer documentation doesn't belong in manuals. > > > > Just to avoid misunderstandings: I wouldn't object to splitting > > qemu-doc.texi into a user manual and developer documentation. > > That really boils down to moving chapter 6 somewhere else; everything > else is user documentation. I think we should start with Dan's patch, > and then integrate it with any missing information from chapter 6. With GNU autotools you get a generic INSTALL file which describe the way you use configure to build. I'd suggest we just move chapter 6 to be an INSTALL file in plain text, and just have the README file point people in that direction. Keep qemu-doc.texi as purely the runtime usage manual Regards, Daniel
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. + + +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 + + ./configure + make + sudo make install + +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 + + +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 +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 +========= + + - 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). + + - 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
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 <berrange@redhat.com> --- README | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 2 deletions(-)