aboutsummaryrefslogtreecommitdiffstats
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
parentFix: setup.py (diff)
downloadeo_bindings-4c6ba609cd1b383d5c12aa731b7a77ce820e8989.tar.gz
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 @@
-##################
+#####################################################
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 introspection is set of tools to generate high-level
-language bindings for C libraries based on Eo(E Object) library,
-which 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 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.
-EO Introspection provides easy generation
-of Python and JS bindings for your library based on Eo.
+ 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.
#####################################################
-COMPILING AND INSTALLING
- python-dev package is required,
- because package needs to compile source c files
- Install python-dev package:
- > sudo apt-get install python-dev build-essential
+1. Compiling and installing
- Installing eoparser:
+ 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.
+ PYTHONPATH env_var must be provided.
+
+
+ 1.3 To compile Cython files, cython (0.17) is required.
- To compile Cython files, cython (0.17) is required.
Install pip (python installs packages):
> sudo apt-get install python-pip
Install cython:
@@ -39,40 +76,147 @@ COMPILING AND INSTALLING
> pip install --upgrade cython
-
-
-#
-#
-#####################################################
-
-Tools:
- Scanner
- Graph Generator
- Python code generator
- JS code generator
-
#####################################################
-Scanner is a part of EObject introspection module.
-It analyzes source and header C files, which can contain EO-styled class definition,
- and generates XML - description for each found class
-#####################################################
+2. Introspecting folder and building class graph:
-1. Introspecting folder:
+ 2.1 Folder introspection
Scanner runs recursively on defined folders
- a. > python eo_xml_gen.py --dir=IN_DIR --dir=IN_DIR2 --outdir=OUT_DIR -include=INCLUDE_DIR
- script searches for dependency xmlfiles in Python env paths.
- if PYTHONPATH wasn't set explicit --include=INCLUDE_DIR can be needed
+ > python eo_xml_gen.py --dir=IN_DIR --dir=IN_DIR2 --outdir=OUT_DIR -include=INCLUDE_DIR
+ script searches for dependencies in Python env paths.
+ If dependencies are not in Python search path,
+ --xmldir=XML_DIR can be needed
- b. Building classes graph chart:
- Graph generator runs recursively on defined folders and generates graphviz dot file,
- which can be used to generate image
+ 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
- > python eo_graph_gen.py --dir=FOLDER_WITH_XML1 --dir=FOLDER_WITH_XMLS --outfile=graph.png
+ > python eo_graph_gen.py --dir=FOLDER_WITH_XML1
+ --dir=FOLDER_WITH_XMLS --outfile=graph.png
> eog graph.png
-2. Generating python-bindings: read /eo_py/README
+
+#####################################################
+3. Generating python bindings
+
+ 3.1 Generating python module for classes defined in XMLs:
+ > python 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.
+ And it can be used as following:
+ from eorepo.eobase import EoBase
+
+#####################################################################
+
+4. Generating js module for classes defined in XMLs:
+ a. > python 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
+
+####################################################################
+
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 @@
-############################################################################
-
-EO Introspection - JavaScript Bindings
-
-############################################################################
-
-It analyzes XML files generated by EO introspection scanner and generates
-module, which can be used with V8-based js-engine - elev8.
-
-############################################################################
-
-1. Generating js module for classes defined in XMLs:
- a. > python 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 genratade
-
- following files are needed to compile
- main.cc
- elm.h
- CElmObject.cc
- CElmObject.h
-
- *.so module will be compiled
-
-############################################################################
-############################################################################
-############################################################################
-
-
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 @@
-#########################################################################
-
-EO Introspection - Python Bindings
-
-#########################################################################
-
-It analyzes XML files generated by EO introspection scanner and generates
-python module.
-
-#########################################################################
-
-1. Generating python module for classes defined in XMLs:
- a. > python eo_py_gen.py --dir=XML_FOLDER --outdir=OUTDIR --pkg="lib1 lib2"
- --module=MODULE_NAME --xmldir=INCLUDE_XML_DIR -lname -I/include
- 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 --include=INCLUDE_DIR dir is needed
-
- 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.
-
- b. Compiling module:
- > python setup.py build_ext --inplace
- - module_name.so will be generated.
-
- Put module into python search path and import into your code.
-
-########################################################################
-########################################################################
-########################################################################
-
-2. Creating eobase module:
- a. Create new dir - PY_EOBASE
- (DON'T NAME THIS dir "eobase", because
- this is module name)
- b. Base module folder being introspected - EOBASE
- > python eo_xml_gen.py --dir=EOBASE --outdir=PY_EOBASE
- - eobase.xml will be created in PY_EOBASE
- c. Creating eobase python sources:
- > python eo_py_gen.py --dir=PY_EOBASE --outdir=PY_EOBASE --module=eobase
- --pkg="eo"
- To create base module, option --module must be "eobase"
- - eobase.pxd, eobase.pyx - will be created
- - eodefault.pxd, eodefault.pyx - will be copied into PY_EOBASE
- - setup.py will be created.
- setup.py can be modified in order to add include paths and libraries,
- which weren't mentioned in --pkg option
- d. Compiling python sources into python module.
- > python setup.py build_ext --inplace
- - eodefault.so, eobase.so will be created
- e. Copy __init__.py to PY_EOBASE
- Add PYTHONPATH = PY_EOBASE
-
-