README: fill out some useful quickstart information
PATCH 1/1 README: fill out some useful quickstart information
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.
--- README | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 2 deletions(-)
README +106 -2
@@ -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 [email protected] +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 + + - [email protected] (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
Signature · 1 line
2.4.3
Quoted 27 lines · Daniel P. Berrange
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 <[email protected]>--- README | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 2 deletions(-)README +1
-1@@ -1,3 +1,107 @@ -Read the documentation in qemu-doc.html or on http://wiki.qemu-project.org + QEMU README
README line 10
Quoted 10 lines
README +8
-1+ =========== -- 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).
README line 18
Quoted 8 lines
README +8
-0+ + +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.)
README line 22
Quoted 4 lines
README +4
-0+ + ./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.
README line 30
Quoted 8 lines
README +8
-0+ +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.
Quoted 21 lines
README +21
-0+ + +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 [email protected] +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
README line 61
Quoted 10 lines
README +10
-0+============= + +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"
README line 71
Quoted 10 lines
README +10
-0+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.
Quoted 4 lines
README +4
-0+ + - 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
README line 85
Quoted 10 lines
README +10
-0+ 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+).
Quoted 11 lines
README +11
-0+ - 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
README line 107
Quoted 10 lines
README +10
-0+methods being E-Mail and IRC + + - [email protected] (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
Quoted 30 lines · Peter Maydell
Quoted 29 lines · Daniel P. Berrange
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 <[email protected]>--- README | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 2 deletions(-)README +2
-1@@ -1,3 +1,107 @@ -Read the documentation in qemu-doc.html or on http://wiki.qemu-project.org + QEMU README + ===========
Quoted 10 lines
README line 10
Quoted 8 lines
README +7
-1-- 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.
Quoted 4 lines
Quoted 4 lines
README +4
-0+Building +======== + +QEMU is multi-platform software intended to be buildable on all modern Linux
Quoted 8 lines
README line 18
Quoted 2 lines
README +2
-0+platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other +UNIX targets. The simple process to build QEMU isThis 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.
Quoted 11 lines
README line 22
Quoted 3 lines
README +3
-0+ ./configure + make + sudo make installI 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.
Quoted 2 lines
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
Quoted 12 lines
README line 30
Quoted 9 lines
README +8
-0+ +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/W32We'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.
Quoted 14 lines
README line 71
Quoted 2 lines
README +2
-0+Licensing +=========This section seems to be duplicating the LICENSE file.
Quoted 9 lines
README +9
-0+ + - 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
Quoted 8 lines
README line 85
Quoted 5 lines
README +5
-0+ 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.
Quoted 8 lines
Quoted 8 lines
README +8
-0+Contact +======= + +The QEMU community can be contacted in a number of ways, with the two main +methods being E-Mail and IRC + + - [email protected] (http://lists.nongnu.org/mailman/listinfo/qemu-devel) + - #qemu on irc.oftc.net
Quoted 8 lines
README line 107
Quoted 6 lines
README +6
-0+ +For additional information on contacted the community consult: + + http://qemu-project.org/Contribute/StartHere + +-- EndSome 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
Signature · 4 lines
|: 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 :|
Quoted 23 lines · Daniel P. Berrange
Quoted 14 lines · Peter Maydell
README line 18
Quoted 6 lines · Daniel P. Berrange
README +6
-0+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 isThis 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.
Quoted 4 lines
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.
Quoted 5 lines
Quoted 1 line
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".
Quoted 12 lines
Quoted 11 lines
README line 30
Quoted 8 lines
README +8
-0+ +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/W32We've just significantly improved our documentation for building on OSX, and we should mention it here.
Quoted 7 lines
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.
Quoted 5 lines
Quoted 2 lines
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.
Quoted 17 lines
Quoted 8 lines
Quoted 8 lines
README +8
-0+Contact +======= + +The QEMU community can be contacted in a number of ways, with the two main +methods being E-Mail and IRC + + - [email protected] (http://lists.nongnu.org/mailman/listinfo/qemu-devel) + - #qemu on irc.oftc.netQuoted 8 lines
README line 107
Quoted 6 lines
README +6
-0+ +For additional information on contacted the community consult: + + http://qemu-project.org/Contribute/StartHere + +-- EndSome of the lines in this file seem to be a bit over-long.
Quoted 3 lines
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
Quoted 24 lines · Peter Maydell
Quoted 23 lines · Daniel P. Berrange
Quoted 14 lines · Peter Maydell
README line 18
Quoted 6 lines · Daniel P. Berrange
README +6
-0+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 isThis 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.
Quoted 8 lines
Quoted 4 lines
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 ?
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
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
Signature · 4 lines
|: 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 :|
Quoted 7 lines · Daniel P. Berrange
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
Quoted 33 lines · Daniel P. Berrange
Quoted 32 lines · Peter Maydell
Quoted 30 lines · Daniel P. Berrange
Quoted 17 lines · Peter Maydell
Quoted 8 lines · Daniel P. Berrange
README +4
-0+Building +======== + +QEMU is multi-platform software intended to be buildable onall modern Linux
+platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other
+UNIX targets. The simple process to build QEMU isThis 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.
Quoted 7 lines
Quoted 3 lines
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.
Quoted 5 lines
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.
[...]
Quoted 51 lines · Markus Armbruster
Quoted 33 lines · Daniel P. Berrange
Quoted 32 lines · Peter Maydell
Quoted 30 lines · Daniel P. Berrange
Quoted 17 lines · Peter Maydell
Quoted 8 lines · Daniel P. Berrange
README +4
-0+Building +======== + +QEMU is multi-platform software intended to be buildable onall modern Linux
+platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other
+UNIX targets. The simple process to build QEMU isThis 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.
Quoted 7 lines
Quoted 3 lines
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.
Quoted 8 lines
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
Quoted 19 lines
Quoted 5 lines
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-BUILDNo need for redoing the markup.
[...]
Quoted 68 lines · John Snow
Quoted 52 lines · Markus Armbruster
Quoted 34 lines · Daniel P. Berrange
Quoted 33 lines · Peter Maydell
Quoted 30 lines · Daniel P. Berrange
Quoted 17 lines · Peter Maydell
Quoted 8 lines · Daniel P. Berrange
(quoted diff) +4
-0+Building +======== + +QEMU is multi-platform software intended to be buildable onall modern Linux
+platforms, OS-X, Win32 (via the Mingw64 toolchain) and a variety of other
+UNIX targets. The simple process to build QEMU isThis 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.
Quoted 7 lines
Quoted 3 lines
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.
Quoted 8 lines
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:
Quoted 6 lines
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.
Quoted 12 lines
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.
Quoted 4 lines
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.
Quoted 10 lines · Markus Armbruster
Quoted 10 lines
"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
Quoted 13 lines · Paolo Bonzini
Quoted 11 lines · Markus Armbruster
Quoted 9 lines · John Snow
"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"
Quoted 4 lines
Quoted 1 line
Quoted 1 line
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.
Quoted 5 lines · Markus Armbruster
Quoted 2 lines
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
Quoted 6 lines · Paolo Bonzini
Quoted 3 lines · Markus Armbruster
Quoted 2 lines
I don't think this is necessary. We should remove duplicate information from qemu-doc.texi, developer documentation doesn't belong in manuals.
Quoted 6 lines
Quoted 2 lines
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
Signature · 4 lines
|: 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 :|
Quoted 13 lines · Daniel P. Berrange
README +13
-0+ +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/,
README line 91
Quoted 10 lines
README +10
-0+ 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
Quoted 66 lines · Daniel P. Berrange
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 <[email protected]>--- README | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 2 deletions(-)README +38
-2@@ -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 +
README line 49
Quoted 10 lines
README +10
-0+When submitting patches, the preferred approach is to use 'git format-patch' +and/or 'git send-email' to format & send the mail to the [email protected] +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.
README line 61
Quoted 12 lines
README +12
-0+ +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?)
Quoted 19 lines
README +19
-0+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
README line 90
Quoted 10 lines
README +10
-0+ 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: "
README line 92
Quoted 2 lines
README +2
-0+ 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.
README line 99
Quoted 7 lines
README +7
-0+ +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."
README line 104
Quoted 5 lines
README +5
-0+ - [email protected] (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:"
README line 107
Quoted 4 lines
README +3
-0+ 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