diff --git a/docs/modules/box2d.md b/docs/modules/box2d.md index 86bcf13e..0fb1f50e 100644 --- a/docs/modules/box2d.md +++ b/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 diff --git a/docs/modules/os.md b/docs/modules/os.md index 46bdc3a0..5ef676bf 100644 --- a/docs/modules/os.md +++ b/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()` diff --git a/docs/quick-start/config.md b/docs/quick-start/config.md index e3b90545..8586304b 100644 --- a/docs/quick-start/config.md +++ b/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 ``` -## 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 +``` + +### Full config You can create a `user_config.h` in the same directory as `pocketpy.h` to override some default settings. diff --git a/docs/quick-start/dylib.md b/docs/quick-start/dylib.md index 13d67de0..c92d2493 100644 --- a/docs/quick-start/dylib.md +++ b/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. diff --git a/docs/quick-start/exec.md b/docs/quick-start/exec.md index 011351df..849c3276 100644 --- a/docs/quick-start/exec.md +++ b/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_MODE); - std::cout << CAST(int, result); // 123 + std::cout << py_cast(vm, result); // 123 }catch(Exception& e){ // use e.summary() to get a summary of the exception std::cerr << e.summary() << std::endl; diff --git a/docs/quick-start/installation.md b/docs/quick-start/installation.md index 50fea8d9..4332c228 100644 --- a/docs/quick-start/installation.md +++ b/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 @@ -49,18 +57,33 @@ using namespace pkpy; int main(){ // Create a virtual machine 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_MODE); - std::cout << CAST(int, result); // 6 + PyObject* result = vm->eval("sum(a)"); + std::cout << py_cast(vm, result); // 6 + + // Bindings + vm->bind(vm->_main, "add(a: int, b: int)", + [](VM* vm, ArgsView args){ + int a = py_cast(vm, args[0]); + int b = py_cast(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(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.