Dear LLVMers, LLVM is currently undergoing a change in its programming API, most of which has to do with the transition to using an LLVMContext. I've been trying to keep two LLVM projects, poolalloc and SAFECode, up-to-date with LLVM mainline, but it has become frustrating because: 1) The API changes occur frequently. Each morning I come in and have to fix something because the API changed. 2) The necessary changes aren't advertised on llvmdev; I have to go figure out for myself the new way to do whatever it is that my code does (adding constant NULL pointers, adding constant integers, etc.). When making API changes, could you please consider doing the following: 1) If technically possible, add the new API first, get it working, email llvmdev describing the old and new APIs, provide some lead time for people to change over, and then remove the old APIs. This makes it easier to plan when I fix problems due to LLVM API changes and when I can work on our own bugs. :) 2) When an API change is going to be made/has been made, please send a short email to llvmdev stating what has/will be changed and how LLVM users should update their code. If you can write a script that makes the change automatically, that would be even better, but I realize that some changes are complicated enough that automating the change is too much effort. It saves time when I know what is going to break and how to fix it; scrounging around the LLVM source and the commit mailing list is wasted time when a two sentence email will tell me everything I need to know. -- John T.
On Jul 15, 2009, at 7:44 AM, John Criswell wrote:> 1) If technically possible, add the new API first, get it working, > email > llvmdev describing the old and new APIs, provide some lead time for > people to change over, and then remove the old APIs. This makes it > easier to plan when I fix problems due to LLVM API changes and when I > can work on our own bugs. :)The high-level change was already described and discussed on LLVMdev. The summary is that the static factory methods on Constant and Type are going away, and becoming instance methods on LLVMContext. All of the instance methods are already in place (though many just forward to the static implementations for the moment). I'm currently in the process of moving the implementations over, removing the static versions, and updating the LLVM tree for it. For basic constant-fetching API changes, which make up the bulk of the changes, the update should be trivial: switching to the corresponding instance method on LLVMContext. In general, I've tried to make the mapping of static function names to instance method names obvious, so it should be straightforward. Slightly more tricky are the API changes made incidentally to moving to LLVMContext, like the GlobalValue constructor change. These occurred because it was necessary to pass a context in where it wasn't available before. I'll try to provide more notice about these, but, again, they should be relatively limited in scope. --Owen -------------- next part -------------- A non-text attachment was scrubbed... Name: smime.p7s Type: application/pkcs7-signature Size: 2620 bytes Desc: not available URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20090715/3a3b2b6c/attachment.bin>
Owen Anderson wrote:> On Jul 15, 2009, at 7:44 AM, John Criswell wrote: > >> 1) If technically possible, add the new API first, get it working, >> email >> llvmdev describing the old and new APIs, provide some lead time for >> people to change over, and then remove the old APIs. This makes it >> easier to plan when I fix problems due to LLVM API changes and when I >> can work on our own bugs. :) >> > > The high-level change was already described and discussed on LLVMdev. >First, did you discuss it or announce it? There's a difference. With its high traffic volume, I don't read all llvmdev mails anymore. I pick and choose based on their subject lines. A subject entitled "API Change: LLVMContext" will probably get my attention while "Multi-threading support for LLVM" will not. Second, the only emails I remember on the topic was an email that provided a short description of LLVMContext and some followup emails on questions/commit messages from me. The first message announcing LLVMContext was too vague; it required that the reader think about the LLVM implementation and logically deduce what was going to change. The text you've written below is much more clear: you say methods x, y, and z are moving from class a to b. That information and doxygen is usually all I need. What I'm suggesting is that you should announce a change in a way that makes it easy for LLVM users to understand what they need to do to understand their code. The announcement can't assume that the reader knows about LLVM internals (like how uniquing is implemented), and it can't be part of some larger discussion on how the change should be made. What you've written below is perfect; I think it would have been better if you had sent it earlier. Perhaps you did, and I missed it, or perhaps I'm being too picky. In that case, I apologize. I think I've said enough on the matter. My points are meant as constructive criticism; use them in whatever way you feel is best. -- John T.> The summary is that the static factory methods on Constant and Type > are going away, and becoming instance methods on LLVMContext. All of > the instance methods are already in place (though many just forward to > the static implementations for the moment). I'm currently in the > process of moving the implementations over, removing the static > versions, and updating the LLVM tree for it. > > For basic constant-fetching API changes, which make up the bulk of the > changes, the update should be trivial: switching to the corresponding > instance method on LLVMContext. In general, I've tried to make the > mapping of static function names to instance method names obvious, so > it should be straightforward. > > Slightly more tricky are the API changes made incidentally to moving > to LLVMContext, like the GlobalValue constructor change. These > occurred because it was necessary to pass a context in where it wasn't > available before. I'll try to provide more notice about these, but, > again, they should be relatively limited in scope. > > --Owen