Fwd: [DOCS] Review requested: How to Setup an Arch Linux Buildbot

[Mikael Lyngvig]

I think I found a way to reconcile the two documents.  I added this passage
to the beginning of the chapter on how to install a Buildbot slave:

     This chapter is a more specific, detail-oriented version of the
high-level documentation found in :doc:`HowToAddABuilder`.  Please refer to
that document for a more generic view of what we do in this chapter.

That way I can keep the specific procedure of how to set up an Arch Linux
Buildbot slave while making the reader aware that the other document exists.

What do you think?  I'd be rather unhappy about having to throw away steps
from the detail-oriented document as the ultimate goal is to make it so
trivially easy to add builders that many more do so.


-- Mikael

---------- Forwarded message ----------
From: Mikael Lyngvig <mikael at lyngvig.org>
Date: 2013/11/22
Subject: Re: [DOCS] Review requested: How to Setup an Arch Linux Buildbot
To: Renato Golin <renato.golin at linaro.org>
Cc: Mikael Lyngvig <mikael at lyngvig.org>, LLVM-commits <
llvm-commits at cs.uiuc.edu>


Houston, we have a slight problem...

I looked into referencing the existing document (How to Add a Builder).
 And it is very terse, albeit correct, but the main issue is that I cannot
avoid replicating some of the steps in my document.  For instance, I guide
the reader through setting up a master and a slave.  Later on, I reuse the
already set up slave.  That kind of goes against what is said in the
existing document and I actually have to make a cludge of sorts: "Then you
need replace 'lab.llvm.org' with 'localhost' if you have set up a Buildbot
master."  It all gets rather messy because of the requirement that there
must be no redundancy.  Another problem is that I only need to reuse a few
steps of the existing document, the rest are simply too different because
of the way that I guide the user through setting up a Buildbot master.

I think perhaps you should think of my document like the Kaleidoscope
sample: It is a hands-on tutorial on doing something and it cannot but help
to be somewhat redundant.  You could also argue that the Kaleidoscope
sample might not have any redundancy, but then you'd end up virtually
without anything in the sample because it necessarily repeats things that
are already part of the IR reference manual.

One day, when we get an actual layered structure of the documentation, I
think this new document should be located in a section for "hands-on
experience with LLVM" whereas the existing Buildbot document should remain
a core part of the reference documentation.

I simply cannot find any good way to resolve this, but I'll think it over
for a few days and see if something comes up.


-- Mikael


2013/11/22 Renato Golin <renato.golin at linaro.org>

> On 22 November 2013 20:52, Mikael Lyngvig <mikael at lyngvig.org> wrote:
>
>> 1. I'm not sure I need the swap file at all after I switched to using
>> Gold.  I guess I should try it out before I submit the document to be
>> committed.  The swap file will only be used if needed, so it shouldn't slow
>> down the build unless it is really needed.  How do you use Gold in the
>> proper way?  LD=ld.gold cmake ...?
>>
>
> On Debian, when you install binutils-gold, the system already updates the
> alternatives to use that by default, so you don't need to do anything. I
> don't know Arch well enough to know how it will behave. My Arch system
> seems to have gold already, and ld is a hardlink (or a copy) to ld.bfd. In
> this case, using the autoconf/cmake alternatives for selecting the
> toolchain is recommended, or a symlink. (in this case it's ok because gold
> IS a linker, while ccache is NOT gcc).
>
>
> 2. I must admit that I am blissfully unaware of CMake supporting CCache?
>>  What do I need to to use CCache the proper way? :-)  Is it only a matter
>> of using: CC="ccache gcc" CXX="ccache g++" cmake ...?  Besides, I believe
>> the given configuration uses Autoconf and not CMake.  It might be better to
>> use CMake, though.
>>
>
> Yes, it should be just a matter of setting the appropriate toolchain
> selection on autoconf/cmake. CC and CXX should just work.
>
>
> 3. I am aware that there's already a document on how to set up a buildbot
>> slave, but I am aiming for a single one-shot document that describes all
>> steps in a single document.  I'll put in a link and consider if the
>> existing document needs updates (which I don't think).  My plan is actually
>> to make all in all three of these walk-through documents: Arch Linux,
>> Debian, and Windows.  After that, I feel people should have sufficient info
>> to set up a buildbot slave without further instructions.
>>
>
> What we normally do in LLVM docs is to never duplicate anything. So, if
> there is a doc on buildslaves, you add a small paragraph saying to look at
> the other document, and come back when you finished. It's better in the
> long run than having to update lots of documents (in your case, three at
> least) later when things change. ;)
>
> cheers,
> --renato
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20131123/d7a3122c/attachment.html>