cleanup the repository

Author: aoloe

README.md

@@ -14,10 +14,24 @@ You will have to first get pybind11, compile it, and install it:
 
 The pybind11 authors prefer adding pybind11 as a git sub-project: you can of course follow their instruction and adapt the `CMakeLists.txt` files in this repository.
 
+## The development environment
+
+You need:
+
+- a development environment for C++ (g++ or clang; cmake, ...)
+- the Python bindings (`libpython3-dev`, `python-cxx-dev`, ...)
+
+Our [first example](add/) directly uses the compiler, all other examples will need a modern version of `cmake` being installed (pybind11 should have cmake 3.4)
+
 ## Sample projects
 
-- [`add/`](add/): the first example.
-- [`add-cmake`](add-cmake/): the first example with cmake
+- [`add/`](add/): using a c++ module to add two numbers in Python
+- [`add-cmake`](add-cmake/): the first example plus cmake
+- [`classes/`](classes/): let Python use C++ classes
+- [`eval-file/`](eval-file/): C++ evaluates a Python script in an external files that modifies the state of a C++ variable.
+- [`eval-set-object/`](eval-set-object/): Create two objects of type `Foo` and pass them to a Python script (defined as a string in the C++ code)
+- [`eval-set-object-module/`](eval-set-object-module/): Create a `.so` module for the `Foo` type, load it get the Python script to access it.
+- [`eval-file-pyqt5/`](eval-file-pyqt5/): The C++ code runs an external Python script that shows a PyQt5 alert.
 - ...
 
 ## Links
@@ -32,3 +46,26 @@ The pybind11 authors prefer adding pybind11 as a git sub-project: you can of cou
 ## alternatives
 
 - [cppy](https://pypi.python.org/pypi/cppyy) is an automatic Python-C++ bindings generator designed for large scale programs in high performance computing that use modern C++.
+
+## todo
+
+document all directories:
+
+- [x] add
+- [x] add-cmake
+- [ ] classes
+- [ ] eval-file
+- [ ] eval-set-object
+- [ ] eval-set-object-module
+- [ ] eval-file-pyqt5
+- [ ] eval-file-pyqt5-set-value
+- [ ] scripter-api
+- [ ] scripter-class
+- [ ] scripter-class-in-class
+- [ ] scripting
+- [ ] scripting-pyqt5
+- [ ] qt5-pyqt5
+
+open questions:
+
+- [ ] how to pass sys.argv to the `QApplication()` in `eval-file-pyqt5/python/pyqt5.py`

add-cmake/CMakeLists.txt

@@ -5,8 +5,6 @@ set(PYBIND11_PYTHON_VERSION 3.4)
 
 find_package(pybind11 CONFIG)
 
-include_directories(src)
-
 pybind11_add_module(maths
     src/maths.cpp
 )

add-cmake/README.md

@@ -1,9 +1,13 @@
 # pybind11 and cmake
 
-Adding `cmake` to avoid the complex `g++` call in the [add example](../add).
+This second example shows how to use cmake to simplify the compilation of the [add example](../add).
+
+Using `cmake` avoid us the use of the complex `g++` call in the [add example](../add).
 
 Like all examples in this repository we're not binding `pybind11` as a git submodule but compile it separately in `~/bin`
 
+The `pybind11_DIR` passed to the cmake commands tells the compiler where to find the library.
+
 There is an official demo project that fetches pybind11 as a git submodule: <https://github.com/pybind/cmake_example>.
 
 ~~~.sh

add/README.md

@@ -1,43 +1,45 @@
 # Add: the first example
 
-- install `python3-cxx-dev`
-- this is the command the documentation is suggesting:  
+This first example shows how to create a python module providing the `add()` function that returns the sum of the two integers given as a parameter.
 
-  ~~~.sh
-  c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` maths.cpp -o maths.so
-  ~~~
+This is the compile command that works for me:
+
+```.sh
+c++ -O3 -shared -fPIC -std=c++11 -I ~/src/pybind11/include -I /usr/include/python3.5 -L /usr/lib/python3 `python-config --cflags --ldflags` maths.cpp -o maths.so
+```
 
-- using
+As a result ou will get the python library `maths.so`.
 
-  ~~~.sh
-  c++ -O3 -fPIC -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` maths.cpp -o maths.so
-  ~~~
+You can now import the "maths" module in Python3. Start Python3 in the directory where the file is located and:
 
-  i get `undefined reference to `main'`
-- so it gets:
+```.py
+>>> import maths
+>>> print(maths.add(1,2))
+3
+>>>
+```
 
-  ~~~.sh
-  c++ -O3 -fPIC -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` -c maths.cpp -o maths.so
-  ~~~
+# Notes
 
-  to compile without linking.  
-  but then, in python i get `ImportError: maths.so: only ET_DYN and ET_EXEC can be loaded` because it's not linked.  
-  we need a main, and drop the `-c`.
-- the compilation is working, but when importing the module, python3 complains:
+the pybind11 documentation is suggesting the following:
 
-  ~~~
-  ImportError: dynamic module does not define module export function (PyInit_maths)
-  ~~~
+  ```.sh
+  c++ -O3 -shared -std=c++11 -I <path-to-pybind11>/include `python-config --cflags --ldflags` maths.cpp -o maths.so
+  ```
 
-  we were compiling with python2, but using python3. the `g++` finally is:
+but it fails for me.
 
-  ~~~.sh
-  c++ -O3 -shared -fPIC -std=c++11 -I /home/ale/src/pybind11/include -I /usr/include/python3.5 -L /usr/lib/python3 `python-config --cflags --ldflags` maths.cpp -o maths.so
-  ~~~
+First I need to tell the compiler to use Python3 (since Debian and many other Linux distributions still default to Python2):
+
+  ```.sh
+  c++ -O3 -shared -fPIC -std=c++11 -I ~/src/pybind11/include -I /usr/include/python3.5 -L /usr/lib/python3 `python-config --cflags --ldflags` maths.cpp -o maths.so
+  ```
 
   (<https://docs.python.org/3/extending/embedding.html#compiling-and-linking-under-unix-like-systems>)
 
-- yeah!
+Then I need to add a `main()` function in the `.cpp` file.
+
+Question: (how) can I compile a pure library without any main?
 
 ## Further steps
 

eval-file-pyqt5/CMakeLists.txt

@@ -3,8 +3,17 @@ project(scripting)
 
 set(PYBIND11_PYTHON_VERSION 3.4)
 
-FIND_PACKAGE(pybind11 CONFIG)
+find_package(pybind11 CONFIG)
 
-ADD_EXECUTABLE(scripting src/main.cpp)
-TARGET_LINK_LIBRARIES(scripting ${PYTHON_LIBRARIES})
-TARGET_LINK_LIBRARIES(scripting pybind11::embed)
+add_executable(scripting
+    src/main.cpp
+)
+target_link_libraries(scripting
+    pybind11::embed
+)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/python/pyqt5.py
+    ${CMAKE_CURRENT_BINARY_DIR}
+    COPYONLY
+)

eval-file-pyqt5/README.md

@@ -1,8 +1,10 @@
 # Eval a python script that launches a PyQt5 dialog
 
+The C++ code runs an external Python script that shows a PyQt5 alert.
 
 ~~~.sh
 $ mkdir build
+$ cd build
 $ cmake -Dpybind11_DIR=/home/ale/bin/pybind11/share/cmake/pybind11
 $ make
 $ ./scripting

eval-file-pyqt5/pyqt5.py renamed to eval-file-pyqt5/python/pyqt5.py

@@ -14,3 +14,5 @@ def __init__(self):
     # app = QApplication(sys.argv)
     app = QApplication([])
     ex = App()
+
+

eval-file-pyqt5/src/main.cpp

@@ -1,4 +1,3 @@
-#include <iostream>
 #include <pybind11/embed.h>
 
 namespace py = pybind11;
@@ -9,5 +8,5 @@ int main()
 	py::scoped_interpreter guard{}; // start the interpreter and keep it alive
 
     py::object scope = py::module::import("__main__").attr("__dict__");
-    py::eval_file("../pyqt5.py", scope);
+    py::eval_file("pyqt5.py", scope);
 }

eval-file/CMakeLists.txt

@@ -1,9 +1,20 @@
-CMAKE_MINIMUM_REQUIRED(VERSION 3.4) # 3.4 is better for mac
-PROJECT(scripting)
+cmake_minimum_required(VERSION 3.4)
+project(scripting)
 
-SET(PYBIND11_PYTHON_VERSION 3.4)
+set(PYBIND11_PYTHON_VERSION 3.4)
 
-FIND_PACKAGE(pybind11 CONFIG)
+find_package(pybind11 CONFIG)
 
-ADD_EXECUTABLE(scripting src/main.cpp)
-TARGET_LINK_LIBRARIES(scripting pybind11::embed)
+add_executable(scripting
+    src/main.cpp
+)
+
+target_link_libraries(scripting
+    pybind11::embed
+)
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/python/set-the-y.py
+    ${CMAKE_CURRENT_BINARY_DIR}
+    COPYONLY
+)

eval-file/README.md

@@ -1,11 +1,18 @@
 # Eval a python script that modifies a C++ object
 
-- http://pybind11.readthedocs.io/en/latest/advanced/embedding.html
-- https://github.com/pybind/pybind11/blob/master/tests/test_eval.cpp#L63
+From the C++ code we run a Python script that modifies the state of a C++ variable by calling a C++ function.
+
+In the C++ program we define a `local` list that contains the variable and the function passed to the Python file when evaluating it.
 
 ~~~.sh
 $ mkdir build
-$ cmake -Dpybind11_DIR=/home/ale/bin/pybind11/share/cmake/pybind11 -DPYTHON_EXECUTABLE:FILEPATH=/usr/bin/python3 ..
+$ cd build
+$ cmake -Dpybind11_DIR=~/bin/pybind11/share/cmake/pybind11 ..
 $ make
 $ ./scripting
 ~~~
+
+## References
+
+- http://pybind11.readthedocs.io/en/latest/advanced/embedding.html
+- https://github.com/pybind/pybind11/blob/master/tests/test_eval.cpp#L63