1Extractor, Tweaker, Generator Scripts 2===================================== 3 4What is this stuff? 5------------------- 6 7This directory contains Extractor-Tweaker-Generator (ETG) scripts which are 8used to drive the process of converting the wxWidgets Doxygen XML files into 9the files that will be fed to the bindings generator tool (SIP). 10 11They are each standalone Python scripts (although some refer to others) which 12process the incoming XML for one or more wxWidgets classes, (that is the 13"extractor" part). That XML data is converted to a hierarchy of objects that 14describe the various components of the API (classes, methods, parameters, 15etc.) 16 17Since C++ and Python are different then there are some things which do not 18match perfectly when implementing wrappers of API elements, and we need to do 19some adaptation of the API to make things work. This is the "tweaker" part of 20these scripts, and is typically the bulk of the content of the scripts. The 21objects created by the extractor have methods that help facilitate these 22tweaks, and it is also possible to add new elements as well, when appropriate. 23 24The last thing these scripts do is hand off the tweaked objects to the active 25generators which will traverse the object tree and generate code as needed. 26 27 28Checklist for all new etg files 29------------------------------- 30 31 * Use the bin/make-new-etg-file.py script to create a new boilerplate etg 32 and unittest files for you. In simplest cases all you'll do after that is 33 add the class names to be processed, and add some unittest code for it. 34 35 * Use a filename that matches the wxWidgets/interface/wx file name 36 that the classes and other stuff is being loaded from. This 37 means that there will be lots of very small files in etg, but it 38 will help to find the interface header source to compare what is 39 being declared there with what is being generated, and to better 40 understand what may need tweaked in the etg script file. 41 42 * Read the corresponding interface file and ensure that all classes 43 declared in it are listed in the ITEMS list in the etg file, 44 unless the class should not be wrapped for some reason. Other 45 items from the interface file will be included automatically. 46 47 * Do not list classes from other interface files in the etg file. 48 49 * Check for any extras added to each class in Classic wxPython and 50 evaluate whether the same extras should be added to the Phoenix 51 version. For example, there may be additional methods added 52 on to the class with %extend or %pythoncode that need to be 53 carried over to Phoenix, such as __nonzero__, etc. Also look 54 for methods where Classic indicates that ownership should be 55 transferred, or other special directives. 56 57 * Check for backwards compatibility issues with Classic wxPython 58 and document in the MigrationGuide. Compatibility issues 59 resulting from not renaming all the overloads can probably be 60 left undocumented, we'll probably be adding some of them back as 61 deprecated methods eventually, and the programmers should be 62 able to figure out the rest once they've started porting some 63 code. 64 65 * For window classes check if there are other virtual methods 66 besides those added in addWindowVirtuals() that should be 67 unignored. 68 69 * UNITTESTS! Create a unit test script in the unittests folder 70 using the same base file name. It should at least check that 71 every non-abstract class can be constructed, and should also 72 have tests for things that are added or tweaked in the etg 73 script. Other things that needed no tweaks are ok to be left 74 untested for the time being, although porting over some of the 75 the old unittest code from Classic would also be a good idea, but 76 priority should be given to testing those things that had to be 77 tweaked or added. 78 79