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