# Python Embedded Example Project

This is an example project using mebedded **[python 3.8](https://github.com/python/cpython)** in C++ console application using CMake. This example project also contains **[pybind11](https://github.com/pybind/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! The cpython is +200MB so it may take some time to during `git submodule update`.

```
git clone https://github.com/matusnovak/python-embedded-example-project 
cd python-embedded-example-project 
git submodule init
git submodule update --progress
```

## 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.

## Changing python version

At the time of the creation of this example, Python 3.8 was just released. The cpython submodule is frozen to commit `491bbedc209fea314a04cb3015da68fb0aa63238`. If you want to change python version, change the `branch` in `.gitmodules` to `branch = 2.7` or any other version. See available branches at: <https://github.com/python/cpython>

## 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
```

## fatal error LNK1104: cannot open file 'python38_d.lib'

This happens when you run cmake with `-DCMAKE_BUILD_TYPE=MinSizeRel` and you are compiling the solution in Visual Studio as Debug. Simply, in Visual Studio, change the configuration to the one used in `CMAKE_BUILD_TYPE`.

This happens because the cpython has been built via `CMAKE_BUILD_TYPE` but your Visual Studio is looking for a debug version of the python library (or the other way around).
