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

[Peter Maydell]

On 17 September 2015 at 13:05, Daniel P. Berrange <address@hidden> wrote:
> On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote:
>> On 17 September 2015 at 12:03, Daniel P. Berrange <address@hidden> 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
>> > +
>> > + - address@hidden (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