نظرة على cx_Freeze لتجميع برامج Python

هذا مقال لإلقاء نظرة سريعة على cx_Freeze وليس دليل مفصل لشرح المكتبة.
عند كتابتك لبرنامج بلغة Python, قد تريد إتاحته للمستخدمين, في هذه الحال, عليك جمع البرنامج وملفاته في مجلد وتحويل ملف التشغيل إلى ملف تنفيذي .exe يمكن لWindows التعامل معه بسهولة.
تعرف هذه الخطوات بعمل Build.
أشهر أدوات القيام بهذا الأمر هي مكتبة Pyinstaller, مكتبة بسيطة وسهلة وتتيح لك جمع البرنامج كمجلد أو كملف exe واحد.
وقد استخدمناها في جميع إصدارات WikiSearch باستثناء آخر إصدار.
تبقى Pyinstaller خيار سهل و جيد, لكن لا يعني إنها الأفضل, وليست الأسوأ بالطبع.

ما هي cx_Freeze:

مكتبة cx_Freeze هي مكتبة مفتوحة المصدر, تعمل على تحويل ملفات python إلى ملفات قابلة للتشغيل على مختلف أنظمة التشغيل للكمبيوتر.
وتعمل مع إصدارات python3.9 إلى python3.13 دون أي مشكلة.

بعض ميزات cx_Freeze:

يوجد الكثير لنذكره, لكننا سنذكر البعض بسرعة.

• لا يتم حذف برنامجك غالبًا من برامج الحماية، بعكس Pyinstaller.
• سكربت واحد يعمل على أنظمة مختلفة (Windows / MacOS / Linux).
• يتم عمل كل شيء من خلال ملف python واحد, ما يعني أفكار غير محدودة يمكنك تنفيذها أثناء تجميع البرنامج. لا ترتبط هذه النقطة بالمكتبة نفسها, فيمكنك استدعاء أي مكتبات وتنفيذ أي فكرة تريدها.
• تنفيذ تخصيصات مثل حذف ملفات معينة, نقل أو تغيير أسماء ملفات محددة, أثناء عملية التجميع. وهذا مثال على الأفكار التي تحدثنا عنها.
• إتاحة عمل ملف .exe لتثبيت البرنامج, خيار بدائي.
• استبعاد أي مكتبة تفضلها, حتى إذا كانت مكتبة مدمجة.
• ضغط مكتبات محددة لتقليل الحجم.
• تكامل أفضل مع مختلف أنظمة التشغيل.
• إمكانية نسخ رسائل الخطأ عن طريق Ctrl+C.
• إنشاء عدة ملفات exe مع نفس نسخة Python لتقسيم البرنامج إلى أدوات.

وغير ذلك من الميزات الرائعة, التي تجعل cx_Freeze في نظرنا أفضل خيار.

بعض عيوب cx_Freeze:

بالطبع المكتبة لديها عدة عيوب, سنذكر بعضها.

• لا تتيح تجميع البرنامج في ملف تنفيذي واحد بشكل مباشر كما هو الحال مع pyinstaller, على الرغم من أن هذا الأمر ليس مفضل, نظرًا لأن هذه الخطوة تعني فك ضغط البرنامج في كل مرة تريد فتحه.
• تعرض المسارات لملفات البرنامج في البيئة التي قمت بتجميع البرنامج من خلالها, أمر يمكن التغلب عليه.
• تجمع الكود الخاص بك بنفس المسارات دون ضغطها أو تغيير أسماء الملفات,., على الرغم من ضغط الملفات بشكل افتراضي في pyinstaller, إلا إنك ستكون قادر على الوصول إلى الملفات كما هو الحال هنا.

لماذا cx_Freeze:

قم بكتابة سكربت التجميع, خصص ما تريد الاحتفاظ به, قم بحفظ الملف, وفي كل مرة تريد تحويل برنامجك إلى .exe شغل الملف مع تمرير build واترك له المهمة.
لعمل ملف exe شغل السكربت على Windows, ولعمل ملف لأنظمة أخرى, شغل السكربت على نفس النظام.

نظرة عملية:

في برنامج البيان من نافذة التقنية, نستخدم إطار العمل PyQt6 لواجهة المستخدم GUI.
لإطار العمل هذا الكثير من الملحقات والأدوات, ومنهم نظام كامل لإدارة الوسائط يتضمن ملفات dll بحجم كبير, إلى جانب ملحقات للترجمة وقواعد بيانات, وكلهم أدوات نستخدم بدائل لهم في برنامج البيان, فعند قيامنا بعمل نسخة من البرنامج, سيتم تضمين كل ملحقات المكتبة, يمكننا استبعاد ملحقات معينة أو جعل سكربت التجميع يقوم بهذه المهمة, حيث يقوم بعمل النسخة ثم فتح المجلد وحذف الملفات التي لا نحتاجها.
في كود البيان, نستخدم الاسم الشائع main.py للملف الرئيسي لتشغيل البرنامج, عند التجميع, يقوم السكربت بتغيير اسم الملف إلى Albayan.py ثم تجميع البرنامج لينتج ملف Albayan.exe ثم يعيد تسمية الملف إلى main.py.
كل ما نفعله هو تشغيل سكربت التثبيت, وبذلك, تمكننا من إنشاء GitHub Action يقوم بإنشاء نسخة من البيان عند ما نريد ذلك, وبكل سهولة.

تثبيت المكتبة:

نفذ هذا الأمر.
pip install --upgrade cx_Freeze
ينصح بعمل بيئة وتشغيل المكتبة داخلها.

مثال:

هذه نسخة سابقة من الملف المستخدم مع البيان.
مع إزالة بعض الدوال الخاصة بحذف الملفات, نظرًا لأنها متعلقة بالبيان بشكل مباشر.

import shutil
import sys
import os
from cx_Freeze import setup, Executable
import PyQt6

#Python list تتضمن الملفات والمجلدات الرئيسية المرفقة, مثل الأصوات وبيانات البرنامج وأيقونته والمزيد.
include_files = [
    ("database", "database"),
    ("documentation", "documentation"),
    ("Audio", "Audio"),
    ("bass.dll", "bass.dll"),
    ("Albayan.ico", "Albayan.ico")
]
# خصائص الملف التنفيذي.
build_exe_options = {
    "build_exe": "albayan_build", #اسم المجلد الناتج.
    "optimize": 1, #لإزالة أجزاء غير هامة من الكود مثل assert و docstrings ما يقلل حجم الملف, الخيارات المتاحة بين 0 و 2, 0 لا يزيل شيء, 1 يزيل assert, و2 يزيل assert و docstrings.
    "include_files": include_files, #الملفات والمجلدات التي حددناها سابقًا.
    "packages": ["core_functions", "theme", "ui", "utils"], #المجلدات التي تحتوي على ملفات من Python code للبرنامج.
    "includes": ["PyQt6.QtCore", "PyQt6.QtWidgets", "PyQt6.QtGui", "PyQt6.QtMultimedia", "packaging", "requests", "UniversalSpeech", "sqlalchemy", "sqlalchemy.dialects.sqlite", "apscheduler"], #المكتبات التي نريد تضمينها.
    "excludes": ["tkinter", "test", "setuptools", "pip", "numpy", "unittest"], #مكتبات يتم استبعادها. يمكنك إضافة أي مكتبة, بعد التأكد أن برنامجك لا يحتاجها.
    "include_msvcr": True, #لتضمين إصدارات Visual C++.
    "replace_paths": ["*="] # لاستبدال مسارات الملفات بأسمائها, حل مشكلة عرض مساراتك لدى المستخدمين. يمكن تخصيصه لتجاهل مسارات معينة.
}

setup(
    name="Albayan", #اسم مرفق مع الملف التنفيذي.
    version="3.0.1", #إصدار البرنامج. يمكنك استخدام B للإشارة إلى Beta.
    description="Albayan", #وصف البرنامج, يرفق مع الملف التنفيذي.
    long_description="البيان - Albayan, كل ما يخص الإسلام", #وصف أطول تدعمه بعض أنظمة التشغيل.
    author="TecWindow", #المطور.
    author_email="[email protected]", #بريد المطور.
    url="https://tecwindow.net", #موقع المطور.
    download_url="https://github.com/tecwindow/albayan", #موقع التنزيل.
    options={"build_exe": build_exe_options}, #خصائص عمل exe.
    executables=[
        Executable(
            "Albayan.py", #عمل .exe من ملف Albayan.py أي الملف الرئيسي, يمكنك تضمين المزيد إذا كان برنامجك مصمم بهذه الطريقة, على سبيل المثال, ملف منفصل للتحديثات.
            base="Win32GUI" if sys.platform == "win32" else None, #يستخدم هذا الشرط على Windows فقط لتحديد ما إذا كان البرنامج يدعم GUI.
            target_name="Albayan.exe", #اسم الملف الناتج.
            icon="Albayan.ico", #أيقونة الملف الناتج.
            copyright="2025 tecwindow" #سنة الإصدار.
        )
    ]
)

الآن كل ما يتطلبه الأمر هو حفظ هذا الكود في ملف setup.py أو يمكن استخدام اسم آخر.

تنفيذ السكربت

نفذ التالي في cmd:
setup.py build
أو
python setup.py build
سيقوم الملف بكل شيء.
يمكنك جعله ينفذ ميزات أخرى, ويمكنك العثور على أمثلة لأكثر من إطار عمل, كما يمكنك العثور على اقتراحات كثيرة باستخدام ChatGPT نظرًا لتضمين ملفات توثيق جيدة لهذه المكتبة.
وبالطبع يجب تغيير الأسماء لتناسب مشروعك.

أمور إضافية:

يمكنك تمرير zip_includes أو zip_include_packages لتضمين بعض المكتبات بشكل مضغوط, يقلل الحجم لكن يجعل مدة فتح البرنامج أبطأ.
يمكنك تمرير مستويات الإخراج أيضًا لتحديد نوعية البيانات التي تظهر أثناء تنفيذ التجميع.
يمكنك تمرير نفس القيم من خلال cmd إذا أردت ذلك.
إذا كنت تبحث عن بديل عملي لPyinstaller، فcx_Freeze خيار يستحق التجربة.
توجد المزيد من الخصائص التي ننصح بمراجعتها من هنا.
كما يمكنكم مراجعة الأمثلة من هنا.