[LLVMdev] Undocumented API changes

[Chris Lattner]

On Jun 17, 2009, at 12:06 PM, Mark Shannon wrote:
> Why are there so many undocumented (and as I far I can see)  
> unnecessary
> API changes?

They are only seem unnecessary if you don't understand the reason they  
were made.  We don't make change for change's sake :)

> Recently there has been:
>
> 1.
> For JIT applications, please include llvm/Target/TargetSelect.h and
> call the llvm::InitializeNativeTarget() function before creating an  
> EE.

This fixes long standing linkage problems and helps us move forward  
with cmake.

> 2.
> The major CHANGE is:  the JIT will no longer be safe for executing
> threaded applications without first invoking  
> llvm_start_multithreaded().
>  Please begin to update your client applications now if this affects
> you, as I will be throwing the switch in SVN sooner rather than later.

I don't believe that this is true anymore.  However, the reason for  
this series of changes is to make LLVM multithread safe, so that you  
can have multiple threads JIT'ing at the same time etc.

> 3.
> The change you should make: every call to addPassesToEmitFile,
> addPassesToEmitFileFinish, addPassesToEmitMachineCode, or
> addCommonCodeGenPasses should pass an optimization level enum rather
> than true / false for "Fast". The enum is in
> llvm/Target/TargetMachine.h:

This was made to give more control over optimization level.

> 4.
> The LLVM IR opcodes Add, Sub, and Mul have been each split into two.
> Add, Sub, and Mul now only handle integer types, and three new  
> opcodes,
> FAdd, FSub, and FMul now handle floating-point types.

This is to allow LLVM IR to more accurately model integer overflow,  
which is very important for loop optimization (particularly on 64-bit  
platforms).

> And that's just in a few days!

LLVM moves quickly :)

> I spent a lot of time and effort, getting things to work, first with
> 2.4, then with 2.5 (The changes in the API between 2.4 and 2.5 were  
> more
> than I would have liked, but mainly renaming and caught by the  
> compiler).
>
> Remember, its not just gcc-llvm and clang that use llvm.
>
> So please treat the API with respect.
> Don't change it often, and document EACH and EVERY change.

You'll notice that llvmdev was notified about all of these changes.

> Change (1) above seems to be pointless.
> Why can't the code to create the EE, just call
> llvm::InitializeNativeTarget()?

Because InitializeNativeTarget() is actually more about linking than  
initializing.  You'll notice that all the targets have empty  
implementations of this method.  However, if you don't call this, the  
(e.g.) X86 backend won't get linked into your app.

I'm sorry about API changes, but change is an inherent part of making  
LLVM better.  We will aim to document them in the 2.6 release notes.

-Chris