A procedure manual for quickly publishing a C ++ Python library using pybind11 on Github.

There are many articles that make libraries written in C ++ available from Python using pybind11, I felt that there wasn't much talk about how to publish what I made.

In this article, I will explain the procedure to create a Github repository that can be published based on the template cmake_example officially provided by pybind. If you follow this procedure to the end, you will have a repository that users can install and start using with just a few commands.

1. Clone cmake_example

cmake_example is an official template set up to build with CMake. Get this first.

cd work  #Enter a suitable working directory
git clone https://github.com/pybind/cmake_example.git

2. Create and clone your own Github repository

How to create a repository is omitted. Let's assume that the repository name is mylib. You can freely create .gitignore, but be careful as you will need to combine it with cmake_example later. You can set public / private as you like. Clone if you can.

git clone https://github.com/*****/mylib.git

3. Add pybind11 as a submodule to your Github repository

cd mylib
git submodule add -b master https://github.com/pybind/pybind11.git pybind11

Various downloads are made under the pybind11 / directory, and .gitmodules is generated.

4. Copy the minimum required files

Copy the necessary files & directories from the cmake_example / directory to mylib /. The minimum required items are as follows.

• .gitignore
• CMakeLists.txt
• MANIFEST.in
• LICENSE
• setup.py
• src/

Rename LICENSE to LICENSE.pybind and prepare a separate LICENSE for your project. As mentioned above, for .gitignore, merge your own with cmake_example.

5. Edit CMakeLists.txt

Change the part where cmake_example is written to your own library name.

CMakeLists.txt

cmake_minimum_required(VERSION 2.8.12)
project(mylib) <--

add_subdirectory(pybind11)
pybind11_add_module(mylib src/main.cpp) <--

6. Edit setup.py

Rewrite the setup call part at the bottom with your own information.

setup.py

setup(
    name='mylib', <-
    version='1.0.0', <-
    author='oreore', <-
    author_email='[email protected]', <-
    description='HogeHoge', <-
    long_description='', <-
    ext_modules=[CMakeExtension('mylib')], <-
    cmdclass=dict(build_ext=CMakeBuild),
    zip_safe=False,
)

If necessary, add the requirements of the external library to the description as follows.

    ...
    zip_safe=False,
    packages=find_packages(),
    install_requires=['pillow']

7. Edit the source code

Rewrite the library name to mylib at the specification of PYBIND11_MODULE in main.cpp.

PYBIND11_MODULE(mylib, m) {

After that, create the code as you like and add it to CMakeLists.txt as needed.

8. Build

python setup.py build

OK if there are no errors

9. Install

python setup.py install

10. Check the operation

Go out of the mylib / directory, start python, import the library and check the operation. If you check in mylib /, the files under the current directory may be used instead of the installed files due to the influence of the file search order, so do it outside.

>>> import mylib
>>> mylib.add(1, 2)
>>> 3

11. Commit and publish

To get users to use what you have created, take the following three steps.

11.1. Have a compiler and CMake ready

For Ubuntu etc.

sudo apt install build-essential cmake

You just have to hit it. If you're a Windows user ..., do your best to have Visual Studio 2019 and CMake installed separately (you also need to get CMake through the path, which is painful).

11.2. Have the repository cloned

Ask the user to execute the following command when cloning the repository.

git clone --recursive https://github.com/******/mylib.git

If you do not add --recursive, pybind11 will not be downloaded and you will not be able to build it, so describe it properly.

11.3. Have setup.py run

python setup.py install

I have you hit. that's all.

Supplement 1. If you want to include Python code

If you want to provide not only the C ++ library but also the Python code, change the C ++ library name to _mylib and load it as import from mylib / __ init__.py.

Specifically, first, make CMakeLists.txt as follows.

CMakeLists.txt

project(_mylib)
...
pybind11_add_module(_mylib src/main.cpp)

Then setup.py

setup.py

ext_modules=[CMakeExtension('mylib._mylib')],

This means putting the build artifacts in mylib / _mylib **** (.so or .pyd).

Then src / main.cpp

src/main.cpp

PYBIND11_MODULE(_mylib, m) {

Finally, prepare the mylib / directory where the Python source code is placed and write __init__.py.

mylib/__init__.py

from ._mylib import *

Then add the Python code as you like.

Supplement 2. When developing with Visual Studio 2019

Since I am using CMake, I will generate a solution file for Visual Studio.

Create a build / directory and run cmake in it.

mkdir build
cd build
cmake .. -G "Visual Studio 16 2019"

Since build / mylib.sln is generated, develop using this. The build / directory is included in .gitignore, so if you want to register solution files etc. in the repository, use a different directory instead of build.