summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorYakov Goldberg <yakov.goldberg@gmail.com>2012-12-14 20:15:51 +0200
committerYakov Goldberg <yakov.goldberg@gmail.com>2012-12-16 01:11:54 +0200
commit4c6ba609cd1b383d5c12aa731b7a77ce820e8989 (patch)
treea2b9e0f85e648c8bc4944e58cc47ae3b91c54d70
parent0b0130917656c71699140ca1460bab4aac5ac380 (diff)
README updated. All put in one README file
Signed-off-by: Yakov Goldberg <yakov.goldberg@gmail.com>
-rw-r--r--README228
-rw-r--r--eo_js/README45
-rw-r--r--eo_py/README69
3 files changed, 186 insertions, 156 deletions
diff --git a/README b/README
index fa60406..1d481c7 100644
--- a/README
+++ b/README
@@ -1,36 +1,73 @@
1################## 1#####################################################
2 2
3EO Introspection 3EO Introspection
4 4
5################## 5#####################################################
60. About
71. Compiling and installing
82. Folder Introspection and class graph
93. Generating python bindings
104. Generating JS bindings (elev8 and V8 are required)
11
12####################################################
130. About
14
15 EO introspection is a set of tools to generate high-level
16 language bindings for C libraries based on Eo (E Object) library.
17 Eo is a part of Enlightenent Foundation Libraries.
18 http://svn.enlightenment.org/svn/e/trunk/efl/
6 19
7EO introspection is set of tools to generate high-level 20 Eo library provides an opportunity
8language bindings for C libraries based on Eo(E Object) library, 21 to use object oriented concepts in C.
9which is a part of Enlightenent Foundation Libraries.
10http://svn.enlightenment.org/svn/e/trunk/efl/
11 22
12Eo library provides an opportunity 23 EO Introspection provides easy generation
13to use object oriented concepts in C. 24 of Python and JS bindings for your Eo-based library.
14 25
15EO Introspection provides easy generation 26 Set of tools:
16of Python and JS bindings for your library based on Eo. 27 Scanner
28 Graph Generator
29 Python code generator
30 JS code generator
31
32 Scanner
33 analyzes source and header C files,
34 which can contain EO-styled class definition;
35 and then it generates XML-description for each found class.
36
37 Graph generator
38 builds classes diagram according to XML-descriptions.
39
40 Pyhton code generator
41 analyzes XML files and generates Cython files that are compiled
42 into Python module.
43
44 JS code generator
45 analyzes XML files and generates C++ files that are compiled into
46 elev8 module. Elev8 is V8-based js-engine.
17 47
18##################################################### 48#####################################################
19COMPILING AND INSTALLING
20 49
21 python-dev package is required, 501. Compiling and installing
22 because package needs to compile source c files
23 Install python-dev package:
24 > sudo apt-get install python-dev build-essential
25 51
26 Installing eoparser: 52 1.1 Requirements:
53
54 python-dev package is required, to build extension
55 from source c files.
56 Install python-dev package:
57 > sudo apt-get install python-dev build-essential
58
59 1.2 Installing eoparser:
27 60
28 > python setup.py build 61 > python setup.py build
29 (do this as root unless you are installing in your users directories) 62 (do this as root unless you are installing in your users directories)
30 > python setup.py install 63 > python setup.py install
31 64
65 --prefix option can be used, to install package into user's dir.
66 PYTHONPATH env_var must be provided.
67
68
69 1.3 To compile Cython files, cython (0.17) is required.
32 70
33 To compile Cython files, cython (0.17) is required.
34 Install pip (python installs packages): 71 Install pip (python installs packages):
35 > sudo apt-get install python-pip 72 > sudo apt-get install python-pip
36 Install cython: 73 Install cython:
@@ -39,40 +76,147 @@ COMPILING AND INSTALLING
39 > pip install --upgrade cython 76 > pip install --upgrade cython
40 77
41 78
42
43
44#
45#
46#####################################################
47
48Tools:
49 Scanner
50 Graph Generator
51 Python code generator
52 JS code generator
53
54##################################################### 79#####################################################
55Scanner is a part of EObject introspection module.
56It analyzes source and header C files, which can contain EO-styled class definition,
57 and generates XML - description for each found class
58 80
59##################################################### 812. Introspecting folder and building class graph:
60 82
611. Introspecting folder: 83 2.1 Folder introspection
62 Scanner runs recursively on defined folders 84 Scanner runs recursively on defined folders
63 a. > python eo_xml_gen.py --dir=IN_DIR --dir=IN_DIR2 --outdir=OUT_DIR -include=INCLUDE_DIR 85 > python eo_xml_gen.py --dir=IN_DIR --dir=IN_DIR2 --outdir=OUT_DIR -include=INCLUDE_DIR
64 script searches for dependency xmlfiles in Python env paths. 86 script searches for dependencies in Python env paths.
65 if PYTHONPATH wasn't set explicit --include=INCLUDE_DIR can be needed 87 If dependencies are not in Python search path,
88 --xmldir=XML_DIR can be needed
66 89
67 b. Building classes graph chart: 90 2.2 Building classes graph chart:
68 Graph generator runs recursively on defined folders and generates graphviz dot file, 91 Graph generator runs recursively on defined folders
69 which can be used to generate image 92 and generates png image.
70 93
71# > python eo_graph_gen.py --dir=FOLDER_WITH_XML1 --dir=FOLDER_WITH_XMLS --outfile=OUTFILE.dot 94# > python eo_graph_gen.py --dir=FOLDER_WITH_XML1 --dir=FOLDER_WITH_XMLS --outfile=OUTFILE.dot
72# > dot -Tpng OUTFILE.dot -o out.png 95# > dot -Tpng OUTFILE.dot -o out.png
73# > eog out.png 96# > eog out.png
74 > python eo_graph_gen.py --dir=FOLDER_WITH_XML1 --dir=FOLDER_WITH_XMLS --outfile=graph.png 97 > python eo_graph_gen.py --dir=FOLDER_WITH_XML1
98 --dir=FOLDER_WITH_XMLS --outfile=graph.png
75 > eog graph.png 99 > eog graph.png
76 100
772. Generating python-bindings: read /eo_py/README 101
102#####################################################
1033. Generating python bindings
104
105 3.1 Generating python module for classes defined in XMLs:
106 > python eo_py_gen.py --dir=XML_FOLDER --outdir=OUTDIR
107 --pkg="lib1 lib2" --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR
108 -lname -I/include -DSOME_VAR=1
109
110 --xmldir=XML_DIR - path to search for parent classes
111 (XMLs fith parent classes descriptions)
112
113 Files to be generated:
114 - *.pxi files will be created for each *.xml
115 - *.pxd will be created one for module.
116 - MODULE_NAME.pyx (only one pyx allowed for compiling module)
117 this file includes all *.pxi
118 - setup.py
119 setup.py can be edited in order to add include paths, libraries
120 (which were not mentioned in --pkg option)
121 compile options
122
123 Addition:
124 Sometimes, additional functions, which are not introspectable,
125 must be included. User must implement and add them manually.
126 (Cython knowledge is required)
127
128 To do this, user must provide definitions in *.pxd, *.pxi files,
129 include *.pxi into generated 'module_name.pyx' file and compile.
130
131 3.2 Creating install package and installing generated module:
132 Creating installation package for module
133 > python setup.py sdist
134
135 Building module
136 > python setup.py build
137
138 Installing module (root maybe required)
139 > python setup.py install
140
141########################################################################
142########################################################################
143########################################################################
144
145 3.3 Creating PY base module for Eo base class:
146 Base module folder being introspected - Eo lib itself
147 > python eo_xml_gen.py --dir=(eo lib itself) --outdir=OUTDIR
148 - eobase.xml will be created in OUTDIR folder
149 Creating eobase python sources:
150 > python eo_py_gen.py --dir=OUTDIR --outdir=TMP --module=eobase
151 --pkg="eo" --xmldir=DEFAULT
152 To create base module, option --module must be "eobase".
153 DEFAULT - is a folder with cython files for eodefault module,
154 which provides infrastructure.
155
156 TMP folder will have following layout:
157 tmp\
158 setup.py
159 eorepo\
160 eodefault.pxd
161 eodefault.pyx
162 eobase.pyx
163 eobase.pxi
164 eobase.pxd
165 __init__.py
166
167 - eobase.pxd, eobase.pyx - will be created
168 - eodefault.pxd, eodefault.pyx - will be copied into
169 - __init__.py - will be copied
170 - setup.py will be created.
171 setup.py can be modified in order to add include paths
172 and libraries, which weren't mentioned in command line options
173
174 Creating installation package for module
175 > python setup.py sdist
176
177 Building module
178 > python setup.py build
179
180 Installing module (root maybe required)
181 > python setup.py install
182
183 According to layout, package 'eorepo' will be installed into
184 installation path.
185 And it can be used as following:
186 from eorepo.eobase import EoBase
187
188#####################################################################
189
1904. Generating js module for classes defined in XMLs:
191 a. > python eo_js_gen.py --dir=XML_FOLDER --outdir=OUTDIR
192 --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
193 -DSOME_PATH=\"/path\"
194
195 In case if some class is needed
196 (usually parent class, which is not in the tree being analyzed),
197 include XMLs are searched in python system paths.
198 If include file wasn't found,
199 explicit --xmldir=INCLUDE_DIR dir is needed
200
201 Files to be generated:
202 - *.cc, *.h will be created for each *.xml
203 - _module.cc with EoRegisterModule()
204 if you need to call any functions on module load,
205 add them in this func.
206 - Makefile
207 b. Compiling module:
208 You can edit generated Makefile, if you need to add some additional flags
209 > make
210 - modul_name.so will be genrated
211
212 following files are needed to compile
213 main.cc
214 elm.h
215 CElmObject.cc
216 CElmObject.h
217
218 *.so module will be compiled
219
220####################################################################
221
78 222
diff --git a/eo_js/README b/eo_js/README
deleted file mode 100644
index e013ce7..0000000
--- a/eo_js/README
+++ /dev/null
@@ -1,45 +0,0 @@
1############################################################################
2
3EO Introspection - JavaScript Bindings
4
5############################################################################
6
7It analyzes XML files generated by EO introspection scanner and generates
8module, which can be used with V8-based js-engine - elev8.
9
10############################################################################
11
121. Generating js module for classes defined in XMLs:
13 a. > python eo_js_gen.py --dir=XML_FOLDER --outdir=OUTDIR
14 --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
15 -DSOME_PATH=\"/path\"
16
17 In case if some class is needed
18 (usually parent class, which is not in the tree being analyzed),
19 include XMLs are searched in python system paths.
20 If include file wasn't found, explicit --xmldir=INCLUDE_DIR dir is needed
21
22 Files to be generated:
23 - *.cc, *.h will be created for each *.xml
24 - _module.cc with EoRegisterModule()
25 if you need to call any functions on module load,
26 add them in this func.
27 - Makefile
28 b. Compiling module:
29 You can edit generated Makefile, if you need to add some additional flags
30 > make
31 - modul_name.so will be genratade
32
33 following files are needed to compile
34 main.cc
35 elm.h
36 CElmObject.cc
37 CElmObject.h
38
39 *.so module will be compiled
40
41############################################################################
42############################################################################
43############################################################################
44
45
diff --git a/eo_py/README b/eo_py/README
deleted file mode 100644
index 96c7865..0000000
--- a/eo_py/README
+++ /dev/null
@@ -1,69 +0,0 @@
1#########################################################################
2
3EO Introspection - Python Bindings
4
5#########################################################################
6
7It analyzes XML files generated by EO introspection scanner and generates
8python module.
9
10#########################################################################
11
121. Generating python module for classes defined in XMLs:
13 a. > python eo_py_gen.py --dir=XML_FOLDER --outdir=OUTDIR --pkg="lib1 lib2"
14 --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
15 In case if some class is needed (usually parent class, which is not in the tree being analyzed),
16 include XMLs are searched in python system paths.
17 If include file wasn't found, explicit --include=INCLUDE_DIR dir is needed
18
19 Files to be generated:
20 - *.pxi files will be created for each *.xml
21 - *.pxd will be created one for module.
22 - MODULE_NAME.pyx (only one pyx allowed for compiling module)
23 this file includes all *.pxi
24 - setup.py
25 setup.py can be edited in order to add include paths, libraries
26 (which were not mentioned in --pkg option)
27 compile options
28
29 Addition:
30 Sometimes, additional functions, which are not introspectable,
31 must be included. User must implement and add them manually.
32 (Cython knowledge is required)
33
34 To do this user must provide definitions in *.pxd, *.pxi files,
35 include *.pxi into generated 'module_name.pyx' file and compile.
36
37 b. Compiling module:
38 > python setup.py build_ext --inplace
39 - module_name.so will be generated.
40
41 Put module into python search path and import into your code.
42
43########################################################################
44########################################################################
45########################################################################
46
472. Creating eobase module:
48 a. Create new dir - PY_EOBASE
49 (DON'T NAME THIS dir "eobase", because
50 this is module name)
51 b. Base module folder being introspected - EOBASE
52 > python eo_xml_gen.py --dir=EOBASE --outdir=PY_EOBASE
53 - eobase.xml will be created in PY_EOBASE
54 c. Creating eobase python sources:
55 > python eo_py_gen.py --dir=PY_EOBASE --outdir=PY_EOBASE --module=eobase
56 --pkg="eo"
57 To create base module, option --module must be "eobase"
58 - eobase.pxd, eobase.pyx - will be created
59 - eodefault.pxd, eodefault.pyx - will be copied into PY_EOBASE
60 - setup.py will be created.
61 setup.py can be modified in order to add include paths and libraries,
62 which weren't mentioned in --pkg option
63 d. Compiling python sources into python module.
64 > python setup.py build_ext --inplace
65 - eodefault.so, eobase.so will be created
66 e. Copy __init__.py to PY_EOBASE
67 Add PYTHONPATH = PY_EOBASE
68
69