Packaging pymeos_cffi

This page lists all the things that must be done after a MEOS library update in order to update the pymeos_cffi package accordingly:

• If there has been an API change, start in Step 1
• Otherwise, start in Step 5

1. Update custom header file

Update the custom meos.h header file to get the last changes by running the build_header.py script:

python3 ./pymeos_cffi/builder/build_header.py <path-to-header-file>

2. Test CFFI compilation

This step is always optional since the cffi shared library used will be generated during the build step, but errors will be more clear and easy to detect here.
Generate the shared library by running the build_pymeos.py script:

python3 ./pymeos_cffi/builder/build_pymeos.py

If there is no compilation error, three files should have been generated: a .c, a .o and a .so. Otherwise, look at the errors to see what went wrong. Most likely there is a mismatch between the custom header file and the MEOS header files.

3. Update CFFI Wrapper

Update the function wrappers in functions.py by running the build_pymeos_functions.py script:

python3 ./pymeos_cffi/builder/build_pymeos_functions.py

After finishing, take a look at the generated functions to check there hasn't been any error and that no function is missing. Errors in this wrapper generation will show in the resulting file rather than the exit code.

4. Update Package version number

In the pyproject.toml file, update the version number in version=X.Y.Z so it won't conflict with the existing ones.
You won't be able to publish a package with the same version number as an existing one.

5. Build package

To build the package, run the build python package:

python3 -m build

If everything goes smoothly, two files will have been generated:

• pymeos_cffi-X.Y.Z.tar.gz for source distributions
• pymeos_cffi-X.Y.Z-<architecture-and-version-tags>.whl for wheel (pre-built) distributions

To only generate one of the files, you can pass the flags --sdist to generate only the tar.gz file, or --wheel to generate only the .whl file.

If you are on a linux machine, you won't be able to upload the generated wheel without converting it first into a manylinux wheel. You can do that using the docker image provided in the docker directory.
First, build the image and give it a name:

docker build -t pymeos/builder --no-cache ./docker

⚠️ If you have a previous version of this docker image created, changes in the MEOS repo will go unnoticed and the image won't be recreated. That's why the --no-cache flag is necessary in the build command.

Now, run it to generate the wheels:

docker run --rm -ti -v <path-to-pymeos-project>:/PyMEOS -v <path-to-store-generated-wheels>:/wheelhouse pymeos/builder

For example:

docker run --rm -ti -v /home/diviloper/MobilityDB/PyMEOS:/PyMEOS -v /home/diviloper/MobilityDB/PyMEOS/pymeos_cffi/dist:/wheelhouse pymeos/builder

The docker image will generate manylinux wheels for CPython versions 3.7 to 3.11 and PyPy version 3.7 to 3.9.

6. Upload

To upload the build package into PyPi, you can run twine:

python3 -m twine upload <path-to-file-to-upload>

If you want to upload everything in the dist/ folder, run:

python3 -m twine upload dist/*

It will ask for the credentials before uploading the distributions to PyPi.

7. Congratulate yourself 🥳

🎉🎉🎉 You have uploaded a new version of pymeos_cffi 🎉🎉🎉