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

[John Snow]

On 10/12/2015 01:41 PM, 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 <address@hidden>
> ---
> 
> Changed in v2:
> 
>  - Rewrote initial introduction to explain userspace emulators
>    as well as system emulators
>  - Reformatted to 72 char line width
>  - Illustrate VPATH build instead of in-tree build
>  - Remove duplicated licensing info pointing to LICENSE file
> 
> I've not yet attempted to deal with the possible qemu-tech.texi
> changes discussed in the previous thread, as I figure that's best
> done separately.
> 
>  README | 108 
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 106 insertions(+), 2 deletions(-)
> 
> diff --git a/README b/README
> index c7c990d..819c985 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 & userspace emulator and
> +virtualizer.
> +
> +QEMU is capable of emulating a complete machine in software without any
> +need for hardware virtualization support. By using dynamic translation,
> +it achieves very good performance. QEMU can also integrate with the Xen
> +and KVM hypervisors to provide emulated hardware while allowing the
> +hypervisor to manage the CPU. With hypervisor support, QEMU can achieve
> +near native performance for CPUs. When QEMU emulates CPUs directly it is
> +capable of running operating systems made for one machine (e.g. an ARMv7
> +board) on a different machine (e.g. an x86_64 PC board).
> +
> +QEMU is also capable of providing userspace API virtualization for Linux
> +and BSD kernel interfaces. This allows binaries compiled against one
> +architecture ABI (e.g. the Linux PPC64 ABI) to be run on a host using a
> +different architecture ABI (e.g. the Linux x86_64 ABI). This does not
> +involve any hardware emulation, simply CPU and syscall emulation.
> +
> +QEMU aims to fit into a variety of use cases. It can be invoked directly
> +by users wishing to have full control over its behaviour and settings.
> +It also aims to facilitate integration into higher level management
> +layers, by providing a stable command line interface and monitor API.
> +It is commonly invoked indirectly via the libvirt library when using
> +open source applications such as oVirt, OpenStack and virt-manager.
> +
> +QEMU as a whole is released under the GNU General Public License,
> +version 2. For full licensing details, consult the LICENSE file.
> +
> +
> +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 steps to build QEMU are:
> +
> +  mkdir build
> +  cd build
> +  ./configure
> +  make
> +
> +Complete details of the process for building and configuring QEMU for
> +all supported host platforms can be found in the qemu-tech.html file.
> +Additional information can also be found online via the QEMU website:
> +
> +  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
> address@hidden mailing list. All patches submitted must contain
> +a 'Signed-off-by' line from the author. Patches should follow the
> +guidelines set out in the HACKING and CODING_STYLE files.
> +
> +Additional information on submitting patches can be found online via
> +the QEMU website
> +
> +  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 preferable 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
> +
> +
> +Contact
> +=======
> +
> +The QEMU community can be contacted in a number of ways, with the two
> +main methods being email and IRC
> +
> + - address@hidden
> +   http://lists.nongnu.org/mailman/listinfo/qemu-devel
> + - #qemu on irc.oftc.net
> +
> +Information on additional methods of contacting the community can be
> +found online via the QEMU website:
> +
> +  http://qemu-project.org/Contribute/StartHere
> +
> +-- End
> 

Apologies for my earlier bikeshedding, and thank you for putting effort
into writing some high-level documentation for us.

Reviewed-by: John Snow <address@hidden>