Documentation error in http://llvm.org/docs/LinkTimeOptimization.html

The web page "LLVM Link Time Optimization: Design and Implementation"
contains errors.

In the gray block below "Example of link time optimization" there are
some source files and then a list of commands to execute:

$ llvm-gcc4 --emit-llvm -c a.c -o a.o
$ llvm-gcc4 -c main.c -o main.o
$ llvm-gcc4 a.o main.o -o main

1) in current LLVM (e.g. llvm itself, cfe, llvm-gcc-4.0) no binary with
the name "llvm-gcc4" get's created

Now, let's assume that the gcc compiler from llvm-gcc-4.0 has been meant
and let us substitute therefore "llvm-gcc4" with "llvm-gcc". This gives
us:

$ llvm-gcc --emit-llvm -c a.c -o a.o
$ llvm-gcc -c main.c -o main.o
$ llvm-gcc a.o main.o -o main
a.o: file not recognized: File format not recognized
collect2: ld returned 1 exit status

Okay, that did not really work :-/

This document describes interface between llvm and linker. You need system linker that implements this interface. LLVM tool kit does not supply system linker.

Well, it depends on the configure parameter used while building llvm-gcc. The point is, these examples are not verified with gcc-3.x based llvm-gcc.

Well, it depends on the configure parameter used while building llvm-
gcc.

Hmm, there are other pages on the the website that tell you how you
should configure gcc, e.g. you're led from "How to build the C/C++
Frontend" at http://llvm.org/docs/CFEBuildInstrs.html to Subversion
HEAD (by virtue of an "svn co"). Then you're supposed to look at
README.LLVM. And there you're told to configure like this:

../llvm-gcc4-x.y.source/configure --prefix=`pwd`/../install \
    --enable-llvm=$LLVMOBJDIR --enable-languages=c,c++$EXTRALANGS $TARGETOPTIONS

(You can check this at http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk/README.LLVM)

And if I follow this part of the documentation, then I don't get an
"llvm-gcc4". So either this documentation or the other one should be
fixed, because they're out-of-sync.

The point is, these examples are not verified with gcc-3.x based
llvm-gcc.

This has nothing to do with a 3.x compiler. AFAIK llvm SVN HEAD
doesn't contain any gcc 3.x frontend for LLVM. In fact, I have
4.0.1:

$ llvm-gcc --version
llvm-gcc (GCC) 4.0.1 (Apple Computer, Inc. build 5449)(LLVM build )

Also, the new llvm-top project ALSO creates an "llvm-gcc" binary, that
out of llvm-gcc-4.0

So, neither llvm-top nor llvm-gcc-4.0/trunk/README.LLVM will create
you a "llvm-gcc4" compiler, so the documentation is STILL wrong.

> $ llvm-gcc --emit-llvm -c a.c -o a.o
> $ llvm-gcc -c main.c -o main.o
> $ llvm-gcc a.o main.o -o main
> a.o: file not recognized: File format not recognized
> collect2: ld returned 1 exit status
>
> Okay, that did not really work :-/

This document describes interface between llvm and linker. You need
system linker that implements this interface. LLVM tool kit does not
supply system linker.

I'm not sure this is right. I still think that this is a documentation
error.

The "a.o" file is really a LLVM bitcode file:

$ file *.o
a.o: data
main.o: ELF 32-bit LSB relocatable, Intel 80386, version 1 (SYSV), not stripped

libmagic doesn't know about LLVM bitcode, but rest assured that a.o
*IS* indeed an llvm bitcode file. E.g. "llvm-dis a.o -o -" works.

However, when you call llvm-gcc without --emit-llvm it behaves like a plain
gcc. So it calls the system linker, ld, with this file.

$ strace -oa -efile -ff llvm-gcc a.o main.o -o main
$ grep -h execve a.*
execve("/usr/src/llvm/dist/bin/llvm-gcc", ["llvm-gcc", "a.o", "main.o", "-o", "main"], [/* 38 vars */]) = 0
execve("/usr/src/llvm/dist/libexec/gcc/i686-pc-linux-gnu/4.0.1/collect2", ["/usr/src/llvm/dist/libexec/gcc/i"..., "--eh-frame-hdr", "-m", "elf_i386", "-dynamic-linker", "/lib/ld-linux.so.2", "-o", "main", "/usr/lib/crt1.o", "/usr/lib/crti.o", "/usr/src/llvm/dist/lib/gcc/i686-"..., "-L/usr/src/llvm/dist/lib/gcc/i68"..., "-L/usr/src/llvm/dist/lib/gcc/i68"..., "a.o", "main.o", "-lgcc", ...], [/* 42 vars */]) = 0
execve("/usr/bin/ld", ["/usr/bin/ld", "--eh-frame-hdr", "-m", "elf_i386", "-dynamic-linker", "/lib/ld-linux.so.2", "-o", "main", "/usr/lib/crt1.o", "/usr/lib/crti.o", "/usr/src/llvm/dist/lib/gcc/i686-"..., "-L/usr/src/llvm/dist/lib/gcc/i68"..., "-L/usr/src/llvm/dist/lib/gcc/i68"..., "a.o", "main.o", "-lgcc", ...], [/* 43 vars */]) = 0

See the last line, llvm-gcc calls /usr/bin/ld with "a.o" ...

And it's obvious that the system linker cannot handle LLVM bitcode files,
this linker is for ELF files. Can you tell me ONE system linker that
can load and handle LLVM files? If not, then the documentation still
describes something that doesn't work in real life.

If llvm-gcc in this case was NOT supposed to call the system-linker
with an bitcode a.o file, then llvm-gcc-4.0 in SVN trunk contains a bug.

However, if I'm supposed to run not "llvm-gcc" in step 3 to get a main
program but, say, llvm-ld, then the documentation is wrong again.

Holger,

$ llvm-gcc --emit-llvm -c a.c -o a.o
$ llvm-gcc -c main.c -o main.o
$ llvm-gcc a.o main.o -o main
a.o: file not recognized: File format not recognized
collect2: ld returned 1 exit status

Okay, that did not really work :-/

This document describes interface between llvm and linker. You need
system linker that implements this interface. LLVM tool kit does not
supply system linker.

I'm not sure this is right. I still think that this is a documentation
error.

It is an error on your part misunderstanding purpose of this document. :).

And it's obvious that the system linker cannot handle LLVM bitcode files,
this linker is for ELF files. Can you tell me ONE system linker that
can load and handle LLVM files? If not, then the documentation still
describes something that doesn't work in real life.

This is a document for someone who is interested in updating system linker or someone who has such linker available. If you don't have such linker or you're not interested in updating system linker then this document is not for you. Without this document it is not straight forward to update system linker such that it can handle LLVM bitcode files using LLVMlto library.

BTW, don't assume that there is not any system linker that can handle LLVM bitcode files :slight_smile:

In the gray block below "Example of link time optimization" there are
some source files and then a list of commands to execute:

$ llvm-gcc4 --emit-llvm -c a.c -o a.o
$ llvm-gcc4 -c main.c -o main.o
$ llvm-gcc4 a.o main.o -o main

1) in current LLVM (e.g. llvm itself, cfe, llvm-gcc-4.0) no binary with
the name "llvm-gcc4" get's created

When you build llvm-gcc you can give it any program prefix/postfix name you wish, so its possible to name it llvm-gcc-4.0. However, the main reason behind this was to distinguish from llvm-gcc3 which we supported along with llvm-gcc4. The documentation could be updated to say llvm-gcc but unless you specify the prefix "llvm-" during configure, it wont be named that either :slight_smile:

Devang already answered the second part.

-Tanya

The documentation could be updated to say llvm-gcc
but unless you specify the prefix "llvm-" during configure, it wont be
named that either :slight_smile:

llvm-top did this for you, see the "--program-prefix=llvm-" in
http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk/build-for-llvm-top.sh

(I know that llvm-top hasn't even been announced, but at least when
Reid does this announcement, the page should be changed anyway).

Feel free to send documentation patches to "fix" this.

Well, it depends on the configure parameter used while building llvm-
gcc.

Hmm, there are other pages on the the website that tell you how you
should configure gcc, e.g. you're led from "How to build the C/C++
Frontend" at http://llvm.org/docs/CFEBuildInstrs.html to Subversion
HEAD (by virtue of an "svn co"). Then you're supposed to look at
README.LLVM. And there you're told to configure like this:

../llvm-gcc4-x.y.source/configure --prefix=`pwd`/../install \
    --enable-llvm=$LLVMOBJDIR --enable-languages=c,c++$EXTRALANGS $TARGETOPTIONS

(You can check this at http://llvm.org/svn/llvm-project/llvm-gcc-4.0/trunk/README.LLVM)

Yes, I am familiar with this because I requested it be added.

And if I follow this part of the documentation, then I don't get an
"llvm-gcc4". So either this documentation or the other one should be
fixed, because they're out-of-sync.

My point was that the documentation was originally written such that people would be able to understand that we meant llvm-gcc based upon gcc 4.0. So the documentation is not necessarily incorrect. However, since llvm-gcc3 is dead, we can update the documentation to just be llvm-gcc.

-Tanya