aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: a980af866c54a8377d1c50c5520274c259047b60 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
#####################################################

EO Introspection

#####################################################
0. About
1. Compiling and installing
2. Folder Introspection and class graph
3. Generating python bindings
4. Generating JS bindings (elev8 and V8 are required)

####################################################
0. About

  EO introspection is a set of tools to generate high-level
  language bindings for C libraries based on Eo (E Object) library.
  Eo is a part of Enlightenent Foundation Libraries.
  http://svn.enlightenment.org/svn/e/trunk/efl/

  Eo library provides an opportunity
  to use object oriented concepts in C.

  EO Introspection provides easy generation
  of Python and JS bindings for your Eo-based library.

  Set of tools:
      Scanner
      Graph Generator
      Python code generator
      JS code generator

  Scanner
    analyzes source and header C files,
    which can contain EO-styled class definition;
    and then it generates XML-description for each found class.

  Graph generator
    builds classes diagram according to XML-descriptions.

  Python code generator
    analyzes XML files and generates Cython files that are compiled
    into Python module.

  JS code generator
    analyzes XML files and generates C++ files that are compiled into
    elev8 module. Elev8 is V8-based js-engine.

#####################################################

1. Compiling and installing

   1.1 Requirements:

     python-dev package is required, to build extension
     from source c files.
       Install python-dev package:
       > sudo apt-get install python-dev build-essential

   1.2 Installing eoparser:

     > python setup.py build
     (do this as root unless you are installing in your users directories)
     > python setup.py install

     --prefix option can be used, to install package into user's dir.
     Add install_dir into PYTHONPATH.

   1.3 To compile Cython files, cython (0.17)  is required.

     Install pip (python installs packages):
     > sudo apt-get install python-pip
     Install cython:
     > pip install cython
     or upgrade:
     > pip install --upgrade cython

#####################################################

2. Introspecting folder and building class graph:

   2.1 Folder introspection
    Scanner runs recursively on defined folders
      > eo_xml_gen.py --dir IN_DIR --dir IN_DIR2 --outdir OUT_DIR

      Parent's classes should be found automatically in python search path.
      --xmldir=XML_DIR can be used to add additional search paths.

   2.2 Building classes graph chart:
      Graph generator runs recursively on defined folders
      and generates png image.

#      > python eo_graph_gen.py --dir=FOLDER_WITH_XML1 --dir=FOLDER_WITH_XMLS --outfile=OUTFILE.dot
#      > dot -Tpng OUTFILE.dot -o out.png
#      > eog out.png
      > eo_graph_gen.py --dir FOLDER_WITH_XML1
        --dir FOLDER_WITH_XMLS --outfile graph.png
      > eog graph.png


#####################################################
3. Generating python bindings

   3.1 Generating python module for classes defined in XMLs:
      > eo_py_gen.py --dir XML_DIR --outdir OUTDIR --module MODULE_NAME
      --pkg "lib1 lib2" --xmldir INCLUDE_XML_DIR
      -lname -I/include -DSOME_VAR=1

      Parent's classes should be found automatically in python search path.
      --xmldir=XML_DIR can be used to add additional search paths.

      --xmldir XML_DIR - path to search for parent classes
      (XMLs fith parent classes descriptions)
      --outdir OUTDIR - directory for output. 
      --module - name of module to generate
      --pkg "lib1 lib2" - provide libraries compilation information with pkg-config
      --xmldir - path to parent's classes XMLSw, which are not in search path

      -I - to include search path for headers
      -L - to include search path for libraries
      -l - library to link with
      -D - to define macros

      Files to be generated:
      - *.pxi files will be created for each *.xml
      - *.pxd will be created one for module.
      - MODULE_NAME.pyx (only one pyx allowed for compiling module)
        this file includes all *.pxi
      - setup.py
        setup.py can be edited in order to add include paths, libraries
        (which were not mentioned in --pkg option)
        compile options

      Addition:
         Sometimes, additional functions, which are not introspectable,
         must be included. User must implement and add them manually.
         (Cython knowledge is required)
    
         To do this, user must provide definitions in *.pxd, *.pxi files,
         include *.pxi into generated 'module_name.pyx' file and compile.

   3.2 Creating install package and installing generated module:
      Creating installation package for module
      > python setup.py sdist

      Building module
      > python setup.py build

      Installing module (root maybe required)
      > python setup.py install

########################################################################

   3.3 Creating PY base module for Eo base class:
      Base module folder being introspected - Eo lib itself
        > python eo_xml_gen.py --dir=(eo lib itself) --outdir=OUTDIR
        - eobase.xml will be created in OUTDIR folder
      Creating eobase python sources:
        > python eo_py_gen.py  --dir=OUTDIR --outdir=TMP --module=eobase
        --pkg="eo" --xmldir=DEFAULT
      To create base module, option --module must be "eobase".
        DEFAULT - is a folder with cython files for eodefault module,
        which provides infrastructure.

        TMP folder will have following layout:
        tmp\
           setup.py
           eorepo\
              eodefault.pxd
              eodefault.pyx
              eobase.pyx
              eobase.pxi
              eobase.pxd
              __init__.py

      - eobase.pxd, eobase.pyx - will be created
      - eodefault.pxd, eodefault.pyx - will be copied into
      - __init__.py - will be copied
      - setup.py will be created.
        setup.py can be modified in order to add include paths
        and libraries, which weren't mentioned in command line options

      Creating installation package for module
      > python setup.py sdist

      Building module
      > python setup.py build

      Installing module (root maybe required)
      > python setup.py install

      According to layout, package 'eorepo' will be installed into
      installation path.
      It can be used as following:
      from eorepo.eobase import EoBase

#####################################################################

4. Generating js module for classes defined in XMLs:
     > eo_js_gen.py --dir=XML_FOLDER --outdir=OUTDIR
       --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
       -DSOME_PATH=\"/path\"

      Parent's classes should be found automatically in python search path.
      --xmldir=XML_DIR can be used to add additional search paths.

      --xmldir XML_DIR - path to search for parent classes
      (XMLs fith parent classes descriptions)
      --outdir OUTDIR - directory for output. 
      --module - name of module to generate
      --pkg "lib1 lib2" - provide libraries compilation information with pkg-config
      --xmldir - path to parent's classes XMLSw, which are not in search path

      -I - to include search path for headers
      -L - to include search path for libraries
      -l - library to link with
      -D - to define macros

      Files to be generated:
       - *.cc, *.h will be created for each *.xml
       - _module.cc with EoRegisterModule() func
         if you need to call any functions on module load,
         add them in this func.
       - Makefile

     Compiling module:
       You can edit generated Makefile, if you need to add some additional flags
       > make 
       - modul_name.so will be compiled


       /*
         Need to copy followinf files to compile module, (or static link?)
         main.cc, elm.h, CElmObject.cc, CElmObject.h, _eobase.h, _eobase.c"
       */

####################################################################