aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: ef0ef7793c4b67912bff8fd367134f47f8bdeec4 (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
#####################################################

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.

  Pyhton 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
      script searches for dependencies in Python env paths.
      If dependencies are not in Python search path,
      --xmldir=XML_DIR can be needed

   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_FOLDER --outdir=OUTDIR
      --pkg="lib1 lib2" --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR
      -lname -I/include -DSOME_VAR=1

      --xmldir=XML_DIR - path to search for parent classes
      (XMLs fith parent classes descriptions)

      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:
    a. > eo_js_gen.py --dir=XML_FOLDER --outdir=OUTDIR
         --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
         -DSOME_PATH=\"/path\"

      In case if some class is needed
      (usually parent class, which is not in the tree being analyzed),
      include XMLs are searched in python system paths.
      If include file wasn't found,
      explicit --xmldir=INCLUDE_DIR dir is needed

      Files to be generated:
      - *.cc, *.h will be created for each *.xml
      - _module.cc with EoRegisterModule()
        if you need to call any functions on module load,
        add them in this func.
      - Makefile
   b. Compiling module:
      You can edit generated Makefile, if you need to add some additional flags
      > make 
      - modul_name.so will be genrated

      following files are needed to compile
      main.cc
      elm.h
      CElmObject.cc
      CElmObject.h

      *.so module will be compiled

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