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

["Daniel P. Berrange" <berrange@redhat.com>]

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
-- 
|: 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 :|