[RFC] Improving documentation for ARM

Hi all,

  While building/testing LLVM/Clang on ARM, I often have problems that
are undocumented on the website. I would like to contribute my experience
if possible so that others can benefit from it. If this is a good idea,
I am wondering on what page I should write it down, [1] or [2]?

Regards,
chenwj

[1] http://llvm.org/docs/GettingStarted.html
[2] http://llvm.org/docs/FAQ.html

I think [2] FAQ would be the most appropriate. Or a new document under
user guides:

http://llvm.org/docs/userguides.html#userguides

The FAQ sounds as good a place as any for the "actual information". However, as the recent --abi=aapcs issue has highlighted it may not be obvious that there's a question to ask in the first place. So I'd suggest adding a very brief sentence that there exists information about non-obvious parameters stored in the FAQ to both getting started and testing documents.

Cheers,
David

Why at are the problems you ran into?

(it will be easier to know where to put them the more you tell us
about the nature of the problems)

Also, I believe that GettingStarted.html is outdated in some parts, so
a refresher is certainly in order.

--Sean Silva

Hi Sean,

  Currently, I want to make one note for building LLVM/Clang for ARM,
and the other one for testing. People who building LLVM/Clang on a ARM
board which has no more than 1G memory, should make a swap partition
and use gold to avoid oom. The other one is not so obvious. People who
want to run test cases on ARM should build LLVM/Clang with "--with-abi=aapcs"
option, this is an option not list on `configure --help`, to avoid
false alarm. More details can see in [1].

Regards,
chenwj

[1] http://lists.cs.uiuc.edu/pipermail/cfe-commits/Week-of-Mon-20120917/064690.html

I recommend you copy HowToAddABuilder.rst as a template and put
everything you want to add in a new file HowToBuildOnARM.rst. Just
write up all of the content that you want to add in that document, and
then submit a patch to llvm-commits. At that point, we can then
discuss where best to put it, or whether the content could be merged
with another page. The important thing is writing up all of the
content. As Renato Golin mentioned, it is likely that a new page under
`userguides.rst` will be a good home for it, but that can all be fixed
up later.

If you need any help regarding how to operate the Sphinx
documentation, feel free to ask me. I am currently working on a
document explaining how to operate the Sphinx documentation and
knowing the problems that you run up against helps me to ensure that
the document explains it as well as possible.

--Sean Silva

Here it is:
  http://lists.cs.uiuc.edu/pipermail/llvm-commits/Week-of-Mon-20120924/151570.html

Regards,
chenwj