"Fossies" - the Fresh Open Source Software Archive

Member "glibmm-2.74.0/docs/internal/gmmproc_internals.txt" (19 Sep 2022, 3470 Bytes) of package /linux/misc/glibmm-2.74.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 How it works
    2 ------------
    3 Gtkmmproc is a 3 pass process.
    4 1. Parse .hg/.ccg files and generate meta m4 macros in a tmp file (e.g. gtkmmproc5466.g1)
    5 2. run m4 to expand macro text (to get e.g. (e.g. gtkmmproc5466.g2)
    6 3. snip file into pieces. (.h .private_h, .cc)
    7 
    8 1.
    9 The first pass is to escape anything which may cause problems
   10 with m4 processing of a file.  This pass is performed in perl.
   11 It also implements meta macros which are macros in which
   12 a C++ declaration must be broken into an argument list.
   13 Commands marked with <meta> are implmented at this
   14 level.
   15 
   16 TODO: <meta> ? Is this still true? murrayc
   17 
   18 At this point there is a file (e.g. /tmp/gtkmmproc5466.g1)
   19 which contains text and m4 code. This m4 code is our m4
   20 macros which will be expanded in the next pass.
   21 
   22 2.
   23 The second pass does both expansion and rearrangement of
   24 code.  The entire file including both the .hg headers and the
   25 .ccg source files are processed as one piece.  This is because
   26 some macros expand into multiple sections.  Commands marked
   27 with <m4> are implemented at this level.
   28 
   29 3.
   30 The third pass is to take the M4 output and snip it into
   31 the actually header and implementation files for use.
   32 There are no commands which communicate directly with this layer,
   33 though any raw C++ code from the .hg/.ccg files will of course be
   34 carried through to here.
   35 
   36 All macros are in capitals and are proceed by an underscore.
   37 
   38 
   39 Output files
   40 -------------
   41 
   42 gtkmmproc generates 3 output files.  One is the header for inclusion
   43 in user code.  The other is the implementation including implementing
   44 all the macro built functions.  The last is a private header.  The
   45 private header contains all the functions which are necessary to
   46 derive a C object in the gtk+ object system from this widget.
   47 The private header is not for user consumption.
   48 
   49 
   50 Sectioning
   51 -----------
   52 
   53 Much of the magic of gtkmmproc happens at the m4 level.
   54 This includes sectioning.  Sectioning is method in which a macro
   55 can create pieces of text after or before the expansion of the
   56 macro.  Sectioning is done with the m4 divert command.
   57 The macros _SECTION(), _PUSH() and _POP() are used to
   58 control what section is being writen.
   59 
   60 It is important to understand how the sections of a class
   61 are assembled.
   62 
   63 Example:
   64 
   65   something.hg:
   66     #include <foo.h>
   67 
   68     namespace Gtk {
   69 
   70     class SomeThing
   71       {
   72         WRAP_CLASS(...)
   73         public:
   74         // my methods
   75         void do();
   76       };
   77     }
   78 
   79   something.cmm:
   80     void Gtk::SomeThing::do() {}
   81 
   82 This will be broken up into the following sections
   83 <<>> represents a include section. * marks macro expansions.
   84 (Names don't match current code look at m4 file to see what current
   85 name is.)
   86 
   87   something.h:
   88 *   #ifndef SOMETHING_H
   89 *   #define SOMETHING_H
   90     #include <foo.h>
   91     <<FORWARD>>
   92     namespace Gtk {
   93     class SomeThing {
   94       {
   95 *      public:
   96 *        typedef ...
   97 *        ....
   98        public:
   99        // my methods
  100        void do();
  101 
  102        <<IMPL>>
  103       };
  104 
  105     }
  106     #endif
  107 
  108   something.cc:
  109     void Gtk::SomeThing::do() {}
  110 
  111 *   void gtkmm_something_init_type(
  112 *     ....
  113     <<METHOD>>
  114     <<SIGNAL>>
  115     <<MEMBER>>
  116 
  117   something_p.h:
  118 *   class SomeThing_Class {
  119     <<PRIVATE>>
  120 *   };
  121 
  122 
  123 If you, for example, need to place something in PRIVATE for this
  124 class, you would do
  125 
  126   class SomeThing {
  127      ....
  128   _SECTION(PRIVATE)
  129     my stuff
  130   _SECTION(CLASS)
  131   }
  132 
  133 
  134 In order to improve clarity the m4 template is expanded into
  135 multiple files, one for each type of macro processed.