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

[Markus Armbruster <armbru@redhat.com>]

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.