John Snow <js...@redhat.com> writes:
> On 09/17/2015 12:43 PM, Markus Armbruster wrote:
>> "Daniel P. Berrange" <berra...@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
>>>> <berra...@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
>>>>>> <berra...@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.
