...

docs/modules/box2d.md

@@ -3,11 +3,11 @@ icon: package
 label: box2d
 ---
 
+!!!
+This module is optional. Set `PK_USE_BOX2D` to `1` to enable it.
+!!!
+
 [Box2D](https://box2d.org/) by Erin Catto, the world's best 2D physics engine now becomes a built-in module in pkpy `v1.1.3` and later.
-
-## Setup
-
-You can set option `PK_USE_BOX2D` to `ON` in CMakeLists.txt to enable `box2d` module.
 All platforms are supported, including desktop, mobile and web.
 
 ## Overview

docs/modules/os.md

@@ -4,7 +4,7 @@ label: os
 ---
 
 !!!
-This module is optional to be compiled.
+This module is optional. Set `PK_ENABLE_OS` to `1` to enable it.
 !!!
 
 ### `os.getcwd()`

docs/quick-start/config.md

@@ -4,7 +4,7 @@ label: 'Advanced config'
 order: -2
 ---
 
-## Disable os-related features
+### Disable os-related features
 
 If you want to disable os-related features, you can do this before including `pocketpy.h`.
 
@@ -13,7 +13,17 @@ If you want to disable os-related features, you can do this before including `po
 #include <pocketpy.h>
 ```
 
-## Full config
+### Working with multiple threads
+
+pkpy does not support multi-threading. But you can create multiple `VM` instances and run them in different threads.
+You can do the following to ensure thread safety for `VM` instances:
+
+```cpp
+#define PK_ENABLE_THREAD 1
+#include <pocketpy.h>
+```
+
+### Full config
 
 You can create a `user_config.h` in the same directory as `pocketpy.h` to override some default settings.
 

docs/quick-start/dylib.md

@@ -4,6 +4,10 @@ label: 'Use dynamic library'
 order: 45
 ---
 
+!!!
+This feature is optional. Set `PK_USE_DYLIB` to `1` to enable it.
+!!!
+
 You can import a native module from a dynamic library at runtime.
 This feature is supported on Windows, Linux, macOS, and Android.
 

docs/quick-start/exec.md

@@ -19,6 +19,10 @@ Once you have a `VM` instance, you can execute python code by calling `exec` met
 If the execution is not successful, e.g. a syntax error or a runtime exception,
 the return value will be `nullptr`.
 
+There are also overloaded versions of `exec` and `eval`, which is useful for simple execution:
++ `PyObject* exec(Str source)`
++ `PyObject* eval(Str source)`
+
 ### Compile mode
 
 The `mode` parameter controls how the source code is compiled. There are 5 possible values:
@@ -47,7 +51,7 @@ These two methods are provided for this purpose:
 ```cpp
 try{
     PyObject* result = vm->exec("123", "<eval>", EVAL_MODE);
-    std::cout << CAST(int, result);   // 123
+    std::cout << py_cast<int>(vm, result);   // 123
 }catch(Exception& e){
     // use e.summary() to get a summary of the exception
     std::cerr << e.summary() << std::endl;

docs/quick-start/installation.md

@@ -9,7 +9,7 @@ You have two options to integrate pkpy into your project.
 #### Use the single header file
 
 Download the `pocketpy.h` on our [GitHub Release](https://github.com/blueloveTH/pocketpy/releases) page.
-And `#include` it in your project.
+And `#include` it in your project. It is recommended to use the latest dev version.
 
 #### Use CMake
 
@@ -23,6 +23,11 @@ In your CMakelists.txt, add the following lines:
 option(PK_BUILD_STATIC_LIB "Build static library" ON)
 add_subdirectory(pocketpy)
 target_link_libraries(your_target pocketpy)
+
+if(EMSCRIPTEN)
+    # exceptions must be enabled for emscripten
+    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fexceptions")
+endif()
 ```
 
 These variables can be set to control the build process:
@@ -39,6 +44,9 @@ To compile it with your project, these flags must be set:
 + `--std=c++17` flag must be set
 + Exception must be enabled
 
+For emscripten, you must enable exceptions to make pocketpy work properly.
+See https://emscripten.org/docs/porting/exceptions.html.
+
 ### Example
 
 ```cpp
@@ -51,16 +59,31 @@ int main(){
     VM* vm = new VM();
 
     // Hello world!
-    vm->exec("print('Hello world!')", "main.py", EXEC_MODE);
+    vm->exec("print('Hello world!')");
 
     // Create a list
-    vm->exec("a = [1, 2, 3]", "main.py", EXEC_MODE);
+    vm->exec("a = [1, 2, 3]");
 
     // Eval the sum of the list
-    PyObject* result = vm->exec("sum(a)", "<eval>", EVAL_MODE);
+    PyObject* result = vm->eval("sum(a)");
-    std::cout << CAST(int, result);   // 6
+    std::cout << py_cast<int>(vm, result);   // 6
+
+    // Bindings
+    vm->bind(vm->_main, "add(a: int, b: int)",
+      [](VM* vm, ArgsView args){
+        int a = py_cast<int>(vm, args[0]);
+        int b = py_cast<int>(vm, args[1]);
+        return py_var(vm, a + b);
+      });
+
+    // Call the function
+    PyObject* f_add = vm->_main->attr("add");
+    result = vm->call(f_add, py_var(vm, 3), py_var(vm, 7));
+    std::cout << py_cast<int>(vm, result);   // 10
+
+    // Dispose the virtual machine
+    delete vm;
     return 0;
-}
 ```
 
 ### Overview
@@ -74,7 +97,7 @@ A process can have multiple `VM` instances. Each `VM` instance is independent fr
 
 !!!
 Always use C++ `new` operator to create a `VM` instance.
-DO NOT declare it on the stack.
+DO NOT declare it on the stack. It may cause stack overflow.
 !!!
 
 ```cpp
@@ -85,7 +108,7 @@ The constructor can take 1 extra parameters.
 
 #### `VM(bool enable_os=true)`
 
-+ `enable_os`, whether to enable OS-related features or not. This setting controls the availability of priviledged modules such os `io` and `os` as well as builtin function `open`.
++ `enable_os`, whether to enable OS-related features or not. This setting controls the availability of priviledged modules such os `io` and `os` as well as builtin function `open`. **It is designed for sandboxing.**
 
 When you are done with the `VM` instance, use `delete` operator to dispose it.