Initial release

Author: Matus Novak

.gitignore

@@ -0,0 +1,7 @@
+build/
+.vs
+.vscode
+*.tmp
+*.suo
+*.TMP
+*.log

.gitmodules

@@ -0,0 +1,8 @@
+[submodule "libs/cpython"]
+	path = libs/cpython
+	url = https://github.com/python/cpython.git
+	branch = 491bbedc209fea314a04cb3015da68fb0aa63238
+[submodule "libs/pybind11"]
+	path = libs/pybind11
+	url = https://github.com/pybind/pybind11.git
+	branch = master

CMakeLists.txt

@@ -0,0 +1,127 @@
+cmake_minimum_required(VERSION 3.1)
+include(${CMAKE_ROOT}/Modules/ExternalProject.cmake)
+project (PythonEmbeddedExample)
+
+# Check for C++11
+set (CMAKE_CXX_STANDARD 11)
+
+# Specify build type
+set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "Select build type")
+set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo" "MinSizeRel")
+
+if (CMAKE_BUILD_TYPE MATCHES "Debug")
+  set(CPYTHON_BUILD_TYPE Debug)
+else ()
+  set(CPYTHON_BUILD_TYPE Release)
+endif()
+
+# Add the cpython as an external project that will be included in the build
+if(MSVC)
+  if(CMAKE_CL_64)
+    set(CPYTHON_PLATFORM x64)
+    set(CPYTHON_BUILD_DIR amd64)
+  else()
+    set(CPYTHON_PLATFORM x86)
+    set(CPYTHON_BUILD_DIR win32)
+  endif()
+  ExternalProject_Add(CPYTHON
+    DOWNLOAD_COMMAND ""
+    SOURCE_DIR ${CMAKE_SOURCE_DIR}/libs/cpython
+    CONFIGURE_COMMAND ""
+    BUILD_COMMAND cd ${CMAKE_SOURCE_DIR}/libs/cpython && MSBuild.exe /p:Configuration=${CPYTHON_BUILD_TYPE} /property:Platform=${CPYTHON_PLATFORM} "PCBuild/python.vcxproj" /nologo /verbosity:minimal /consoleloggerparameters:summar
+    INSTALL_COMMAND ""
+    TEST_COMMAND ""
+  )
+else()
+  ExternalProject_Add(CPYTHON
+    DOWNLOAD_COMMAND ""
+    SOURCE_DIR ${CMAKE_SOURCE_DIR}/libs/cpython
+    CONFIGURE_COMMAND cd ${CMAKE_SOURCE_DIR}/libs/cpython && ./configure --disable-static --enable-shared 
+    BUILD_COMMAND cd ${CMAKE_SOURCE_DIR}/libs/cpython && make
+    INSTALL_COMMAND ""
+    TEST_COMMAND ""
+  )
+endif()
+
+set(CPYTHON_STDLIB_DIR ${CMAKE_SOURCE_DIR}/libs/cpython/Lib)
+if(MSVC)
+  set(CPYTHON_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/libs/cpython/Include ${CMAKE_SOURCE_DIR}/libs/cpython/PC)
+  set(CPYTHON_LIBRARY_DIR ${CMAKE_SOURCE_DIR}/libs/cpython/PCBuild/${CPYTHON_BUILD_DIR})
+  if(CMAKE_BUILD_TYPE MATCHES "Debug")
+    set(CPYTHON_BIN ${CMAKE_SOURCE_DIR}/libs/cpython/PCBuild/${CPYTHON_BUILD_DIR}/python38_d.dll)
+  else()
+    set(CPYTHON_BIN ${CMAKE_SOURCE_DIR}/libs/cpython/PCBuild/${CPYTHON_BUILD_DIR}/python38.dll)
+  endif()
+else()
+  set(CPYTHON_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/libs/cpython/Include ${CMAKE_SOURCE_DIR}/libs/cpython)
+  set(CPYTHON_LIBRARY_DIR ${CMAKE_SOURCE_DIR}/libs/cpython)
+  set(CPYTHON_LIBRARY python3.8m)
+  set(CPYTHON_BIN ${CMAKE_SOURCE_DIR}/libs/cpython/libpython3.8m.so)
+endif()
+
+# Add the pybind11 library (optional)
+ExternalProject_Add(PYBIND
+  DOWNLOAD_COMMAND ""
+  SOURCE_DIR ${CMAKE_SOURCE_DIR}/libs/pybind11
+  CMAKE_ARGS -DPYBIND11_TEST=OFF -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} -DPYTHONLIBS_FOUND=ON -DPYTHON_MODULE_EXTENSION=.lib -DPYTHON_LIBRARY=${CMAKE_SOURCE_DIR}/libs/cpython/PCBuild/win32/python38_d.lib -DPYTHON_INCLUDE_DIR=${CMAKE_SOURCE_DIR}/libs/cpython/PCBuild/win32
+  BUILD_COMMAND cmake --build . --config ${CMAKE_BUILD_TYPE}
+  INSTALL_COMMAND ""
+  TEST_COMMAND ""
+)
+
+set(PYBIND_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/libs/pybind11/include)
+
+# Source and header files
+FILE(GLOB_RECURSE SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/src/*.cpp)
+FILE(GLOB_RECURSE HEADERS ${CMAKE_CURRENT_SOURCE_DIR}/src/*.h)
+
+# Linking directories
+link_directories(${CPYTHON_LIBRARY_DIR})
+
+# The target executable
+add_executable(${PROJECT_NAME} ${SOURCES} ${HEADERS})
+
+# Add macros
+target_compile_definitions(${PROJECT_NAME} PRIVATE NOMINMAX=1)
+
+# Dependencies
+add_dependencies(${PROJECT_NAME} PYBIND)
+add_dependencies(${PROJECT_NAME} CPYTHON)
+
+# Include directories
+target_include_directories(${PROJECT_NAME} PRIVATE ${CPYTHON_INCLUDE_DIR})
+target_include_directories(${PROJECT_NAME} PRIVATE ${PYBIND_INCLUDE_DIR})
+
+# On MSVC build, the python library is automatically linked (crazy I know)
+if(NOT MSVC)
+  target_link_libraries(${PROJECT_NAME} ${CPYTHON_LIBRARY})
+endif()
+
+# Set the executable to console application if MSVC
+if(MSVC)
+	set_target_properties(${PROJECT_NAME} PROPERTIES LINK_FLAGS "/SUBSYSTEM:CONSOLE")
+endif()
+
+# Copy Python DLL to the build folder if different
+add_custom_command(
+  TARGET ${PROJECT_NAME}
+  POST_BUILD
+  COMMAND ${CMAKE_COMMAND}
+  -E copy_if_different ${CPYTHON_BIN} $<TARGET_FILE_DIR:${PROJECT_NAME}>
+)
+
+# Copy our python sources to the build folder
+add_custom_command(
+  TARGET ${PROJECT_NAME}
+  POST_BUILD
+  COMMAND ${CMAKE_COMMAND}
+  -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/src/app $<TARGET_FILE_DIR:${PROJECT_NAME}>/app
+)
+
+# Copy the Python stdlib into the build folder (needed by the embedded python)
+add_custom_command(
+  TARGET ${PROJECT_NAME} 
+  POST_BUILD
+  COMMAND ${CMAKE_COMMAND} 
+  -E copy_directory ${CPYTHON_STDLIB_DIR} $<TARGET_FILE_DIR:${PROJECT_NAME}>/lib
+)

README.md

@@ -0,0 +1,95 @@
+# Python Embedded Example Project
+
+This is an example project using mebedded python 3.8 (cpython) in C++ console application using CMake. This example project also contains pybind11 library for easy binding between C++ and python. 
+
+Tested on Windows 10 with Visual Studio 2013, 2015, and 2017 (both x86 and x64). Also tested on Ubuntu with GCC (x64).
+
+**Note this example has nothing to do with embedding C++ in python! This is the other way around! Embeding python in C++.**
+
+## About
+
+Normally, you have a python installed in your system and then you can launch python scripts from command line. What if you want to create C++ application, but want to use python scripts (for example as modding for games)? One option is to let the user install python on their system and then install your app. No problem there, except, you are forcing the user to modify their system. Additonally, you can never guarantee that the user will install the specific python version (2.7 or 3.8) you require. Even if all of that is sorted out, the python that will get run will probably need third party packages (or you need to explicitly disable some packages), this can't be done easily.
+
+What if we can embed entire python in C++ executable? This way, the user won't have to install python on their system nor additional dependencies. Everything will be bundled up in the executable. 
+
+This project comes with cpython 3.8 (as a git submodule) and pybind11. Once you build the project, your build folder will look like this:
+
+```
+python-embedded-example-project/
+  build/
+    Release/
+      PythonEmbeddedExample.exe
+      app/
+        example.py
+      lib/
+        a lot of Python standard library files
+```
+
+The script files (such as example.py) are copied to the build directory from `src/app` and the python standard libraries are copied over from git submodule located in `python-embedded-example-project/libs/cpython/Lib`. You can't get rid of those standard libraries! Python needs them to initialise. However, you could limit the standard libraries by only selectively copying over the ones you need.
+
+When the executable runs, it will load an `example` module and creates an instance of `Example` class from `example.py` file. That's all it does.
+
+**The python PATH is limited only to the app and lib folder located next to the executable.** The embedded python won't have any access to installed packages in your operating system. You will have to include them in any of those two folders.
+
+## Requirements
+
+Visual Studio 2013 (or newer) or Linux with GCC. MinGW is sadly not supported, and clang has not been tested.
+
+## Download
+
+Don't forget to initialise and update the submodules!
+
+```
+git clone https://github.com/matusnovak/python-embedded-example-project 
+cd python-embedded-example-project 
+git submodile init
+git submodule update
+```
+
+## Build using Visual Studio on Windows
+
+**Please note:** that you have to explicitly specify `CMAKE_BUILD_TYPE`. If you specify Debug, then you must use Debug in your Visual Studio. You won't be able to change to Release using the dropdown list in the main menu. Python will be build using the `CMAKE_BUILD_TYPE` flag regarding the chosen configuration in Visual Studio. To change from Debug to Release, re-run the cmake and set the `CMAKE_BUILD_TYPE` to Release.
+
+```
+cd python-embedded-example-project 
+mkdir build
+cd build
+cmake .. -G "Visual Studio 15 2017" -DCMAKE_BUILD_TYPE=Debug
+```
+
+Then open the generated solution file "PythonEmbeddedExample.sln" in the build folder. You should see the following projects:
+
+* **ALL_BUILD** - Building this will build all projects
+* **CPYTHON** - The embedded python project
+* **PYBIND** - The pybind11 library for binding
+* **PythonEmbeddedExample** - This is the example project
+
+Build the PythonEmbeddedExample and then run the `PythonEmbeddedExample.exe` from command line. That's all.
+
+## Build using GCC on Linux
+
+```
+cd python-embedded-example-project 
+mkdir build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+```
+
+Then build the example by running:
+
+```
+make
+```
+
+The `PythonEmbeddedExample` executable will be generated.
+
+## Example output
+
+Example output of the `PythonEmbeddedExample` executable.
+
+```
+Python PATH set to: C:\Users\matus\Documents\cpp\python-embedded-example-project\build\Debug\lib;C:\Users\matus\Documents\cpp\python-embedded-example-project\build\Debug\app;
+Importing module...Initializing class...
+Example constructor with msg: Hello World
+Got msg back on C++ side: Hello World
+```

libs/cpython

@@ -0,0 +1,7 @@
+class Example:
+    def __init__(self, msg: str):
+        self.msg = msg
+        print('Example constructor with msg:', self.msg)
+
+    def getMsg(self):
+        return self.msg

libs/pybind11

@@ -0,0 +1,99 @@
+#if defined(WIN32) || defined(_WIN32) || defined(__WIN32) && !defined(__CYGWIN__)
+#define IS_WINDOWS
+#include <Windows.h> // Needed by GetModuleFileNameW
+#else
+#include <libgen.h> // Needed by readlink
+#endif
+
+#include <iostream>
+#include <Python.h>
+#ifndef IS_WINDOWS
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#endif
+#include <pybind11/pybind11.h>
+#include <pybind11/eval.h>
+#include <pybind11/embed.h>
+#ifndef IS_WINDOWS
+#pragma GCC diagnostic pop
+#endif
+
+namespace py = pybind11;
+using namespace py::literals;
+
+///=============================================================================
+#ifdef IS_WINDOWS
+std::wstring getExecutableDir() {
+    wchar_t exePath[MAX_PATH];
+    GetModuleFileNameW(nullptr, exePath, MAX_PATH);
+    const auto executableDir = std::wstring(exePath);
+    const auto pos = executableDir.find_last_of('\\');
+    if (pos != std::string::npos) return executableDir.substr(0, pos);
+    return L"\\";
+}
+#else
+std::wstring getExecutableDir() {
+    char result[PATH_MAX];
+    ssize_t count = readlink("/proc/self/exe", result, PATH_MAX);
+    if (count != -1) {
+        const auto path = std::string(dirname(result));
+        return std::wstring(path.begin(), path.end());
+    }
+    return L"/";
+}
+#endif
+
+///=============================================================================
+int main(int argc, char** argv) {
+    (void)argc;
+    (void)argv;
+
+    // Get executable dir and build python PATH variable
+    const auto exeDir = getExecutableDir();
+#ifdef IS_WINDOWS
+    const auto pythonHome = exeDir + L"\\lib";
+    const auto pythonPath = exeDir + L"\\lib;" + exeDir + L"\\app;";
+#else
+    const auto pythonHome = exeDir + L"/lib";
+    const auto pythonPath = exeDir + L"/lib:" + exeDir + L"/app";
+#endif
+
+    // Initialize python
+    Py_OptimizeFlag = 1;
+    Py_SetProgramName(L"PythonEmbeddedExample");
+    Py_SetPath(pythonPath.c_str());
+    Py_SetPythonHome(pythonHome.c_str());
+
+    std::wcout << "Python PATH set to: " << pythonPath << std::endl;
+
+    try {
+        py::scoped_interpreter guard{};
+
+        // Disable build of __pycache__ folders
+        py::exec(R"(
+            import sys
+            sys.dont_write_bytecode = True
+        )");
+
+        // This imports example.py from app/example.py
+        // The app folder is the root folder so you don't need to specify app.example.
+        // The app/example script that is being imported is from the actual build folder!
+        // Cmake will copy the python scripts after you have compiled the source code.
+        std::cout << "Importing module..." << std::endl;
+        auto example = py::module::import("example");
+
+        std::cout << "Initializing class..." << std::endl;
+        const auto myExampleClass = example.attr("Example");
+        auto myExampleInstance = myExampleClass("Hello World"); // Calls the constructor
+        // Will print in the terminal window:
+        // Example constructor with msg: Hello World
+
+        const auto msg = myExampleInstance.attr("getMsg")(); // Calls the getMsg
+        std::cout << "Got msg back on C++ side: " << msg.cast<std::string>() << std::endl;
+    } catch (std::exception& e) {
+        std::cerr << "Something went wrong: " << e.what() << std::endl;
+        return EXIT_FAILURE;
+    }
+
+    return EXIT_SUCCESS;
+}