136 lines
3.4 KiB
Plaintext
136 lines
3.4 KiB
Plaintext
How it works
|
|
------------
|
|
Gtkmmproc is a 3 pass process.
|
|
1. Parse .hg/.ccg files and generate meta m4 macros in a tmp file (e.g. gtkmmproc5466.g1)
|
|
2. run m4 to expand macro text (to get e.g. (e.g. gtkmmproc5466.g2)
|
|
3. snip file into pieces. (.h .private_h, .cc)
|
|
|
|
1.
|
|
The first pass is to escape anything which may cause problems
|
|
with m4 processing of a file. This pass is performed in perl.
|
|
It also implements meta macros which are macros in which
|
|
a C++ declaration must be broken into an argument list.
|
|
Commands marked with <meta> are implmented at this
|
|
level.
|
|
|
|
TODO: <meta> ? Is this still true? murrayc
|
|
|
|
At this point there is a file (e.g. /tmp/gtkmmproc5466.g1)
|
|
which contains text and m4 code. This m4 code is our m4
|
|
macros which will be expanded in the next pass.
|
|
|
|
2.
|
|
The second pass does both expansion and rearrangement of
|
|
code. The entire file including both the .hg headers and the
|
|
.ccg source files are processed as one piece. This is because
|
|
some macros expand into multiple sections. Commands marked
|
|
with <m4> are implemented at this level.
|
|
|
|
3.
|
|
The third pass is to take the M4 output and snip it into
|
|
the actually header and implementation files for use.
|
|
There are no commands which communicate directly with this layer,
|
|
though any raw C++ code from the .hg/.ccg files will of course be
|
|
carried through to here.
|
|
|
|
All macros are in capitals and are proceed by an underscore.
|
|
|
|
|
|
Output files
|
|
-------------
|
|
|
|
gtkmmproc generates 3 output files. One is the header for inclusion
|
|
in user code. The other is the implementation including implementing
|
|
all the macro built functions. The last is a private header. The
|
|
private header contains all the functions which are necessary to
|
|
derive a C object in the gtk+ object system from this widget.
|
|
The private header is not for user consumption.
|
|
|
|
|
|
Sectioning
|
|
-----------
|
|
|
|
Much of the magic of gtkmmproc happens at the m4 level.
|
|
This includes sectioning. Sectioning is method in which a macro
|
|
can create pieces of text after or before the expansion of the
|
|
macro. Sectioning is done with the m4 divert command.
|
|
The macros _SECTION(), _PUSH() and _POP() are used to
|
|
control what section is being writen.
|
|
|
|
It is important to understand how the sections of a class
|
|
are assembled.
|
|
|
|
Example:
|
|
|
|
something.hg:
|
|
#include <foo.h>
|
|
|
|
namespace Gtk {
|
|
|
|
class SomeThing
|
|
{
|
|
WRAP_CLASS(...)
|
|
public:
|
|
// my methods
|
|
void do();
|
|
};
|
|
}
|
|
|
|
something.cmm:
|
|
void Gtk::SomeThing::do() {}
|
|
|
|
This will be broken up into the following sections
|
|
<<>> represents a include section. * marks macro expansions.
|
|
(Names don't match current code look at m4 file to see what current
|
|
name is.)
|
|
|
|
something.h:
|
|
* #ifndef SOMETHING_H
|
|
* #define SOMETHING_H
|
|
#include <foo.h>
|
|
<<FORWARD>>
|
|
namespace Gtk {
|
|
class SomeThing {
|
|
{
|
|
* public:
|
|
* typedef ...
|
|
* ....
|
|
public:
|
|
// my methods
|
|
void do();
|
|
|
|
<<IMPL>>
|
|
};
|
|
|
|
}
|
|
#endif
|
|
|
|
something.cc:
|
|
void Gtk::SomeThing::do() {}
|
|
|
|
* void gtkmm_something_init_type(
|
|
* ....
|
|
<<METHOD>>
|
|
<<SIGNAL>>
|
|
<<MEMBER>>
|
|
|
|
something_p.h:
|
|
* class SomeThing_Class {
|
|
<<PRIVATE>>
|
|
* };
|
|
|
|
|
|
If you, for example, need to place something in PRIVATE for this
|
|
class, you would do
|
|
|
|
class SomeThing {
|
|
....
|
|
_SECTION(PRIVATE)
|
|
my stuff
|
|
_SECTION(CLASS)
|
|
}
|
|
|
|
|
|
In order to improve clarity the m4 template is expanded into
|
|
multiple files, one for each type of macro processed.
|