[LLVMdev] Lost in the documentation

[Hendrik Boom]

On Mon, 28 Apr 2008 17:54:31 -0400, Gordon Henriksen wrote:

> On Apr 28, 2008, at 17:32, Hendrik Boom wrote:
> 
>> In http://llvm.org/docs/FAQ.html, when taking about writing a compiler
>> that uses LLVM (at least I think that's what the FAQ question is
>> asking),
>> the FAQ recommends
>>
>>> #  Call into the LLVM libraries code using your language's FFI
>>> (foreign
>>> function interface).
>>>
>>>    * for: best tracks changes to the LLVM IR, .ll syntax, and .bc
>>>           format
>>>    * for: enables running LLVM optimization passes without a
>>>           emit/parse overhead
>>>    * for: adapts well to a JIT context
>>>    * against: lots of ugly glue code to write
>>
>> Now, which particular libraries would that be
> 
> With the exception of the 'util' and 'tools' directories, the entire
> LLVM source tree consists of libraries.

Indeed, quite a lot of them.  Most of them appear to be internal.  I'm 
trying to identify the ones that are intended for use by LLVM users.

I have to say I missed the crucial paragraph:

: If you go with the first option, the C bindings in include/llvm-c
: should help a lot, since most languages have strong support for
: interfacing with C. The most common hurdle with calling C from managed
: code is interfacing with the garbage collector. The C interface was
: designed to require very little memory management, and so is
: straightforward in this regard.

Evidently I have to go look in include/llvm-c, since I stronlgly suspect 
you didn't go to the trouble of writng a C wrapper for anything that 
wasn't needed by an LLVM user.  Anything internal you'd have left in C++.

So the API for a C++ *user* could be described as "those parts of the 
internals API that happen to be used in implementing llvm-c.

What I found in llvm-c was core.h.  Is that what I need to know for 
writing a compiler front-end?  Let's see.  core.h seems to describe 
building the LLVM code.  BitWriter says how to write it to a file, should 
that be desired.  It's not clear what lto.h, Analysis.h. c/
ExecutionEngine.h do or why I'd need them.  Target.h looks useful if I 
have to include machine-dependencies into my code generator.  Some things 
I do may depend on the size of pionters and the like.


Putting this together with the tutorial, http://llvm.org/docs/tutorial/, 
which uses CAML instead of C, I think I may be able to get a clue.


> 
>> where are their API(s) documented?
> 
> http://llvm.org/docs/
> http://llvm.org/doxygen/
> http://llvm.org/docs/tutorial/
> etc etc etc.
> 
> — Gordon

The doxygen page describes the complete internal structure of LLVM.  It 
explicitly says, 

; This documentation describes the internal software that makes up LLVM,
; not the external use of LLVM. There are no instructions here on how to
; use LLVM, only the APIs that make up the software. For usage
; instructions, please see the programmer's guide or reference manual.

I haven't yet found a "programmer's guide".

The only reference manual I've found so far was "LLVM Language Reference 
Manual", linked from the llvm.org/docs page.  It describes a programming 
language with a syntax.  No doubt it is a textual representation of the 
information to be transmitted using the API I'm looking for, but it 
doesn't document the API.  I can probably find what I'm looking for by 
prowling the source code that implements this LLVM language, and seeing 
what it calls, then looking those classes and methods in the doxygen 
stuff.  That's another way, complementary to guessing the realtionship 
between the ocaml tutorial and Core.h.

-- hendrik