[PATCH] Clang as a cross-compiler documentation

[Sean Silva]

  Please think about the audience that this document is targeted at and keep them in mind.


================
Comment at: docs/CrossCompilation.rst:12-15
@@ +11,6 @@
+
+As you can imagine, this will bring all sorts of problems when interacting
+with your system toolchain. You'll have to find a compiler that can
+generate the target code, a linker that can understand the objects,
+libraries for the specific target, or even more than one target, and so on.
+
----------------
This doesn't add anything. Delete it.

================
Comment at: docs/CrossCompilation.rst:8-10
@@ +7,5 @@
+
+Cross-compiling is the art of building your software with a compiler
+that produces binaries to a different platform, for example, compiling
+ARM binaries on an x86_64 laptop, or Windows binaries on a Linux box.
+
----------------
Move this to the end of the introduction or delete it entirely. I'm pretty sure that this document targets an audience for whom this paragraph adds nothing.

================
Comment at: docs/CrossCompilation.rst:20-21
@@ +19,4 @@
+
+For a concrete example on specific use-cases,
+check http://llvm.org/docs/HowToCrossCompileLLVM.html.
+
----------------
I'm not sure how relevant that specific example is; almost everything there is highly idiosyncratic to LLVM and not necessarily understandable to the audience of this document.

It's probably worth adding a paragraph to the introduction here specifically talking about what's *not* in this document; e.g., it doesn't discuss the options of particular build systems (or in general, it doesn't discuss concrete solutions to the problems it presents; also, maybe a short justification for why it does this (too many possible combinations/idiosyncrasies to adequately discuss a particular case?)).

To avoid confusion, somewhere in the introduction it should be made very clear that this document isn't a "recipe" for cross-compilation with clang. It's simply giving an overview/"concepts" which will probably be helpful/relevant for a person that is trying to get cross-compilation with clang to work in a particular use case.

================
Comment at: docs/CrossCompilation.rst:26-36
@@ +25,13 @@
+
+In GCC world, every host/target combination has its own set of binaries,
+headers, libraries, etc. So, it's usually simple to download a package
+with all files in, unzip to a directory and point the build system to
+that compiler, that will know about its location and find all it needs to
+when compiling your code.
+
+But Clang/LLVM is natively a cross-compiler, meaning that one set of
+programs can compile to all targets by setting the -target option. But that
+doesn't help finding the headers, libraries or binutils to generate
+target specific code. So you'll need special options to help Clang understand
+what target you're compiling to, where are your tools, etc.
+
----------------
These two paragraphs baffle me. It's basically like "Cross-compilation with GCC is easy, but clang arbitrarily doesn't do it that way and everything is therefore much more difficult". Is that really the message you're trying to get across? The way that this is written even makes the sentence "clang/llvm is natively a cross-compiler" sound like a weakness, rather than a strength.

Also, I'm not sure why it's necessary/relevant to devote a paragraph to how GCC does things; does that help the reader understand anything? It seems like the relevant comparison is with how native (i.e. non-cross) builds with Clang/LLVM find headers/libraries/tools/etc.

================
Comment at: docs/CrossCompilation.rst:17-18
@@ +16,4 @@
+
+This document will guide you in choosing the right options for the right
+job, and hopefully help you in cross-compiling between any two architectures.
+
----------------
This is going in the right direction, but is extremely vague. Please be specific. At the very least, answer:

* Why would I want to read this document? (e.g. maybe "this document is targeted at developers that would like to know what capabilities are provided by Clang/LLVM tools for doing cross-compilation")
* What should I know to be able to follow along with this document? (e.g. maybe "only a basic understanding of cross-compilation is necessary; difficulties inherent to cross-compilation are introduced before describing functionality that deals with them")
* What will I have learned by the end of this document? (Maybe "after reading this document, you should be familiar with the main issues related to cross-compilation and what compiler options Clang provides for performing cross-compilation")


http://llvm-reviews.chandlerc.com/D1606