[docs] HowToCrossCompileLLVM.rst: update cmake options

[fourdim]

Summary

This patch updates the cmake options suggested when cross compiling. This should fix #52819.

Brad King (Member of CMake) says:

The linked CMAKE_CROSSCOMPILING documentation says:

This variable will be set to true by CMake if the CMAKE_SYSTEM_NAME variable has been set manually (i.e. in a toolchain file or as a cache entry from the cmake command line).

It is not meant to be set by project code or toolchain files. It is always set automatically. Don't put set(CMAKE_CROSSCOMPILING ON) anywhere in your code.

CMAKE_CROSSCOMPILING indicates only whether CMAKE_SYSTEM_NAME was set by the user/project/toolchain-file instead of by CMake.

In LLVM project, CMAKE_CROSSCOMPILING is used to determine whether to execute some tests on the host machine.

LLVM needs to use another method for that. CMAKE_CROSSCOMPILING is not a reliable indicator of whether produced binaries will run on the host, and does not claim so in its documentation. If one sets CMAKE_SYSTEM_NAME to Linux in a toolchain file, and builds on a Linux host, that doesn't mean the target architecture or minimum glibc version is the same.

[fourdim]

Update the format.

[lancethepants]

Good needed change.

[rengolin]

Nice catch, thanks!

[rengolin]

I think you forgot to upload the new diff for the GCC comment. It's looking the same as before for me.

(PS: this is one of the problems of Phab to me, it can be confusing with git diff + patch + upload).

[rengolin]

In D119804#3333462, @rengolin wrote:

I think you forgot to upload the new diff for the GCC comment. It's looking the same as before for me.

Hm, there wasn't any. But I did get a comment on the email that I wanted to reply to and it isn't here. Won't change the acceptance of the patch, it's more as FYI.

If you're compiling with GCC, you can use architecture options for your target, and the compiler driver will detect everything that it needs

This is a common thread between Clang and GCC.

In GCC, the target is defined at compile time, so if you use target-gcc, all of the options are already chosen. Paths, headers, libraries, even sysroot is already set.

Clang also has target-clang (as a symlink to clang), but that's a shortcut to clang -target target, which may have some headers but doesn't have libraries, sysroot and may not get the right path (if the platform compiler is GCC and compiled in unexpected ways).

That is why we need the other flags and why this document was written in the first place.

We have debated for years if we want to have a default LLVM sysroot+libs+headers, and some side projects have started in that direction, but we shouldn't use a different toolchain from the system one if we want to link with objects compiled with the system compiler (statically or dynamically).

In FreeBSD, Apple and OpenMandriva, Android, the system compiler is clang, so all libraries, paths and the sysroot should be easy to find and known, and clang does what you expect, too.

But on other Linux distros, Windows and systems where the system toolchain isn't clang, you'll have that problem again.

[fourdim]

In D119804#3333462, @rengolin wrote:

I think you forgot to upload the new diff for the GCC comment. It's looking the same as before for me.

(PS: this is one of the problems of Phab to me, it can be confusing with git diff + patch + upload).

I'm confused about which GCC comment should be updated. Would you please point out that file or that line?
I'll plan to create a new patch to fix that.

[fourdim]

In D119804#3333467, @rengolin wrote:

In D119804#3333462, @rengolin wrote:

I think you forgot to upload the new diff for the GCC comment. It's looking the same as before for me.

Hm, there wasn't any. But I did get a comment on the email that I wanted to reply to and it isn't here. Won't change the acceptance of the patch, it's more as FYI.

If you're compiling with GCC, you can use architecture options for your target, and the compiler driver will detect everything that it needs

This is a common thread between Clang and GCC.

In GCC, the target is defined at compile time, so if you use target-gcc, all of the options are already chosen. Paths, headers, libraries, even sysroot is already set.

Clang also has target-clang (as a symlink to clang), but that's a shortcut to clang -target target, which may have some headers but doesn't have libraries, sysroot and may not get the right path (if the platform compiler is GCC and compiled in unexpected ways).

That is why we need the other flags and why this document was written in the first place.

We have debated for years if we want to have a default LLVM sysroot+libs+headers, and some side projects have started in that direction, but we shouldn't use a different toolchain from the system one if we want to link with objects compiled with the system compiler (statically or dynamically).

In FreeBSD, Apple and OpenMandriva, Android, the system compiler is clang, so all libraries, paths and the sysroot should be easy to find and known, and clang does what you expect, too.

But on other Linux distros, Windows and systems where the system toolchain isn't clang, you'll have that problem again.

Well, that seems a great challenge. Hope we will achieve that soon.

[rengolin]

In D119804#3333468, @fourdim wrote:

I'm confused about which GCC comment should be updated. Would you please point out that file or that line?
I'll plan to create a new patch to fix that.

Ah, it was NOT a comment! It was just the next few lines from the docs itself. And I think I wrote that myself all those years ago... : D

Not to worry, the docs look good, thanks!

llvm/docs/HowToCrossCompileLLVM.rst

 Configuring CMake
 -----------------
 
 For more information on how to configure CMake for LLVM/Clang,
 see :doc:`CMake`.
 
 The CMake options you need to add are:
 
- * ``-DCMAKE_CROSSCOMPILING=True``
+ * ``-DCMAKE_SYSTEM_NAME=<target-system>``
  * ``-DCMAKE_INSTALL_PREFIX=<install-dir>``
  * ``-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen``
  * ``-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen``
  * ``-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf``
  * ``-DLLVM_TARGET_ARCH=ARM``
  * ``-DLLVM_TARGETS_TO_BUILD=ARM``
 
+Note: ``CMAKE_CROSSCOMPILING`` is always set automatically when ``CMAKE_SYSTEM_NAME`` is set. Don't put ``-DCMAKE_CROSSCOMPILING=TRUE`` in your options.
+
 If you're compiling with GCC, you can use architecture options for your target,
 and the compiler driver will detect everything that it needs:
 
  * ``-DCMAKE_CXX_FLAGS='-march=armv7-a -mcpu=cortex-a9 -mfloat-abi=hard'``
 
 However, if you're using Clang, the driver might not be up-to-date with your
 specific Linux distribution, version or GCC layout, so you'll need to fudge.