CythonExtensionTemplate

This project provides a Cython template that can be easily compiled into a standalone .exe file. The compiled executable can run without requiring a Python interpreter, using compiled .pyd files. This setup ensures seamless execution of Python code within a compiled environment, making it an ideal solution for creating Python-based applications that are portable and independent of the Python installation.

Features

• Standalone .exe Generation: Convert Cython code into a Windows executable (.exe) that doesn’t require an external Python interpreter.
• No Dependencies on Python Installation: The .exe runs with compiled .pyd files, eliminating the need for a pre-installed Python environment.
• Fully Customizable Template: Ready to modify and tweak according to your project’s specific requirements. Easily extendable for your use cases.
• Supported Platform: This template is only tested for Windows!

Getting Started

Prerequisites

• Python 3.x (any version compatible with Cython)
• Cython (installable via pip)
• Microsoft Visual C++ Build Tools (for compiling C extensions)
• CMake 3.14

Installation

1. Clone this repository:

   git clone https://github.com/urban233/CythonExtensionTemplate.git
   cd CythonExtensionTemplate

2. Setup virtual environment:

   Set up a virtual environment under the root directory and call it .venv (this is required for the make.bat file)

3. Install dependencies:

   Install Cython via pip:

   pip install cython

4. Modify the Template:

   The template contains the standalone script (main.pyx) and Cython file (core/mymodule.pyx). Modify these files to implement your desired functionality.

5. Compile the Cython code:

   In the root directory of the project, run the following command to compile the Cython code into .pyd files:

   .\make.bat build-pyx

6. Generate the Executable:

   Use the make.bat script to convert the Cython script into a standalone .exe file:

   .\make.bat rebuild-c

   This will generate the .exe file in the dist/ directory.

Running the Executable

You can test the .exe file by initially running:

.\make.bat setup-test

and after that you can run:

.\make.bat test

Make.bat script

The make.bat script is used for most tasks related to build procedures.

Usage:
   rebuild-c:         Rebuilds the entire Visual Studio 2022 project to build the main.exe
   build-c:           Builds the Visual Studio 2022 project to create the main.exe
   build-pyx:         Builds the pyx files into a pyd
      --clean:        Cleans the build directory of the pyx build
   setup-test:        Sets up the Lib test directory
   test:              Tests the pyx files in combination with the main.exe

Customization

You can easily modify the template to suit your specific needs. Here are a few common customizations:

• Add new Cython files: Simply add additional .pyx files, and ensure they are imported properly in main.pyx.
• Modify Cython code: Update mymodule.pyx with your custom Cython logic. Rebuild the .pyd files after making changes.
• Customizable build process: You can tweak the build process by modifying the setup.py or the PyInstaller configuration.

Contributing

Contributions are welcome! If you'd like to improve this template or add new features, feel free to open a pull request. Please ensure that your changes are well-documented and include tests where applicable.

License

This project is licensed under the GNU GPLv3 License - see the LICENSE file for details.