قواعد الكتابة على نظام التشغيل Windows

تركّز هذه الصفحة على كتابة القواعد المتوافقة مع نظام التشغيل Windows والمشاكل الشائعة المتعلقة بكتابة القواعد المحمولة وبعض الحلول.

المسارات

المشاكل:

  • الحدّ الأقصى للطول: الحد الأقصى لطول المسار هو 259 حرفًا.

    وعلى الرغم من أنّ نظام التشغيل Windows يتيح أيضًا المسارات الأطول (حتى 32767 حرفًا)، فإنّ العديد من البرامج مصمَّمة بحد أدنى.

    انتبه إلى هذا البرنامج الذي تشغّله في الإجراءات.

  • دليل العمل: يقتصر أيضًا على 259 حرفًا.

    لا يمكن للعمليات cd أن تدخل في دليل أطول من 259 حرفًا.

  • حساسية لحالة الأحرف: مسارات Windows غير حساسة لحالة الأحرف، كما أن مسارات Unix حسّاسة لحالة الأحرف.

    يُرجى الانتباه إلى ذلك عند إنشاء أسطر أوامر للإجراءات.

  • فواصل المسارات: هي شرطة مائلة للخلف (\`), not forward slash (/`).

    يخزّن Bazel المسارات على طراز Unix باستخدام فواصل /. على الرغم من أنّ بعض برامج Windows تتوافق مع مسارات نظام التشغيل Unix، ولا يدعمها البعض الآخر. تتوافق بعض الأوامر المدمجة في cmd.exe، وبعض الأمر't.

    من الأفضل دائمًا استخدام \` separators on Windows: replace/with` عند إنشاء أسطر أوامر ومتغيرات بيئة للإجراءات.

  • المسارات المطلقة: لا تبدأ بشرطة مائلة (/).

    تبدأ المسارات المطلقة على نظام التشغيل Windows بحرف محرك الأقراص، مثل C:\foo\bar.txt. ليس هناك جذر نظام ملف واحد.

    انتبه إلى ما إذا كانت القاعدة تتحقّق مما إذا كان المسار مطلقًا أم لا. ويجب تجنّب المسارات المطلقة لأنها غالبًا ما تكون غير قابلة للنقل.

الحلول:

  • حافِظ على طول المسارات.

    تجنّب استخدام أسماء الدليل الطويلة، وبُنى الأدلة المتداخلة بشدة، وأسماء الملفات الطويلة، وأسماء مساحات العمل الطويلة، وأسماء الاستهداف الطويلة.

    وقد تحوّل كل هذه المسارات إلى مكوّنات مسار للإجراءات&#39؛ وملفات إدخال، وقد تستنفد الحدّ الأقصى لطول المسار.

  • استخدِم جذرًا قصيرًا للمخرجات.

    استخدِم العلامة --output_user_root=<path> لتحديد مسار قصير لمخرجات Bazel. ومن الأفكار الجيدة أن يكون لديك محرك أقراص (أو محرك أقراص افتراضي) مخصص لمخرجات Bazel (مثل ملف D:\`), and adding this line to your.bazelrc):

    build --output_user_root=D:/

    أو

    build --output_user_root=C:/_bzl

  • استخدِم التوصيلات.

    تتمثّل ال التوصيلات في التحدث بشكل متّسق[1]، وهي تُمثّل روابط رمزية للدليل. من السهل إنشاء التوصيلات ويمكن أن تشير إلى الأدلة (على جهاز الكمبيوتر نفسه) التي تحتوي على مسارات طويلة. إذا كان إجراء الإنشاء ينشئ تقاطعاً مساره قصيرًا ولكن هدفه طويل، يمكن للأدوات التي لها حد مسار قصير الوصول إلى الملفات في الدليل التقاطعي'ed.

    في .bat ملف أو في cmd.exe، يمكنك إنشاء تقاطعات مثل:

    mklink /J c:\path\to\junction c:\path\to\very\long\target\path

    [1]: بشدة

  • استبدِل / بـ `` في المسارات في الإجراءات/المحلات.

    عند إنشاء متغيّر سطر الأوامر أو بيئة الإجراء، يمكنك إنشاء مسارات بنظام التشغيل Windows. مثال:

    def as_path(p, is_windows):
    if is_windows:
        return p.replace("/", "\\")
    else:
        return p

متغيرات البيئة

المشاكل:

  • حساسية لحالة الأحرف: أسماء متغيّرات بيئة Windows غير حساسة لحالة الأحرف.

    على سبيل المثال، في Java System.getenv("SystemRoot") وSystem.getenv("SYSTEMROOT") تؤدي إلى النتيجة نفسها. (ينطبق هذا على اللغات الأخرى أيضًا.)

  • التوافق: يجب أن تستخدم الإجراءات أقل عدد ممكن من متغيرات البيئة المخصصة.

    متغيّرات البيئة هي جزء من مفتاح ذاكرة التخزين المؤقت للإجراء. وإذا كان أحد الإجراءات يستخدم متغيّرات البيئة التي تتغيّر كثيرًا، أو إذا كانت مخصّصة للمستخدمين، يؤدي ذلك إلى تقليل إمكانية تخزين القاعدة في ذاكرة التخزين المؤقت.

الحلول:

  • استخدِم أسماء متغيّرات الأحرف الكبيرة فقط.

    ويعمل هذا على أنظمة التشغيل Windows وmacOS وLinux.

  • تقليل بيئات العمل

    عند استخدام ctx.actions.run، يمكنك ضبط البيئة على ctx.configuration.default_shell_env. إذا كان الإجراء يحتاج إلى المزيد من متغيرات البيئة، يمكنك وضعها في قاموس وتمريرها إلى الإجراء. مثال:

    load("@bazel_skylib//lib:dicts.bzl", "dicts")

def _make_env(ctx, output_file, is_windows):
    out_path = output_file.path
    if is_windows:
        out_path = out_path.replace("/", "\\")
    return dicts.add(ctx.configuration.default_shell_env, {"MY_OUTPUT": out_path})

الإجراءات

المشاكل:

  • المخرجات القابلة للتنفيذ: يجب أن يحتوي كل ملف تنفيذي على امتداد قابل للتنفيذ.

    الإضافات الأكثر شيوعًا هي .exe (الملفات الثنائية) و.bat (النصوص البرمجية المجمّعة).

    يُرجى العلم بأن نصوص واجهة برمجة التطبيقات (.sh) غير قابلة للتنفيذ على نظام التشغيل Windows، ولا يمكنك تحديدها على أنها ctx.actions.run's executable. لا يتوفّر أيضًا إذن +x الذي يمكن أن تمتلكه الملفات، لذا لا يمكنك تنفيذ الملفات العشوائية مثل التي تعمل بنظام التشغيل Linux.

  • الطلبات المُجمّعة: لتسهيل عملية التنقّل، تجنَّب تشغيل أوامر Bash مباشرة في الإجراءات.

    Bash منتشر على نطاق واسع في الأنظمة التي تشبه Unix، ولكنها غالبًا غير متاحة على نظام التشغيل Windows. إنّ Bazel بحدّ ذاتها يعتمد على أنظمة أقل في Bash (MSYS2)، وبالتالي يقلّ احتمال تثبيت أجهزة MSYS2 في المستقبل مع Bazel. لتسهيل استخدام القواعد على نظام التشغيل Windows، تجنَّب تشغيل أوامر Bash في الإجراءات.

  • نهايات الأسطر: يستخدم نظام التشغيل Windows قائمة الشهادات الباطلة (CRLF) (\r\n)، وتستخدم الأنظمة التي تشبه نظام التشغيل Unix LF (\n).

    يُرجى الانتباه لذلك عند مقارنة الملفات النصية. انتبِه إلى إعدادات Git، لا سيما نهايات الأسطر عند إتمام الدفع أو الالتزام. (راجع إعداد core.autocrlf Git's).

الحلول:

  • استخدام قاعدة معدّة لغرض غير محدّد:

    native.genrule() هو برنامج استخدام لأوامر Bash، وغالبًا ما يُستخدم لحل مشاكل بسيطة، مثل نسخ ملف أو كتابة ملف نصي. يمكنك تجنّب الاعتماد على باش (إعادة تصميم العجلة): اطّلِع على ما إذا كانت قاعدة Bazel-skylib قاعدة مخصّصة وفقًا لاحتياجاتك. ولا يعتمد أي منها على Bash عند اختباره أو اختباره على Windows.

    أمثلة على إنشاء القاعدة:

    • copy_file() (المصدر, المستندات): ينسخ ملفًا في مكان آخر، ما يجعله قابلاً للتنفيذ اختياريًا

    • write_file() (المصدر أو المستندات): يكتب ملفًا نصيًا يحتوي على نهايات الأسطر المطلوبة (auto أو unix أو windows)، ما يجعله اختياريًا قابلاً للتنفيذ (إذا كان نصًا برمجيًا)

    • run_binary() (المصدر، المستندات): يتم تشغيل برنامج ثنائي (أو قاعدة *_binary) مع مدخلات معينة والمخرجات المتوقعة كإجراء إصدار (هذا برنامج تضمين قاعدة لـ ctx.actions.run)

    • native_binary() (المصدر، المستندات): يتم تضمين برنامج ثنائي أصلي في قاعدة *_binary، والتي يمكنك استخدامها bazel run أو استخدامها في سمة run_binary()'s tool أو سمة native.genrule()'s tools.

    أمثلة على قواعد الاختبار:

  • على نظام التشغيل Windows، ننصحك باستخدام نصوص برمجية من .bat للأشياء غير المهمة.

    بدلاً من استخدام .sh نص برمجي، يمكنك حلّ المهام البسيطة باستخدام نصوص برمجية من .bat.

    على سبيل المثال، إذا كنت بحاجة إلى نص برمجي لا يفعل أي شيء أو طباعة رسالة أو الخروج باستخدام رمز خطأ ثابت، يكفي توفير ملف .bat بسيط. إذا كانت القاعدة تعرض موفّر خدمة DefaultInfo()، قد يشير الحقل executable إلى ملف .bat هذا على نظام التشغيل Windows.

    وبما أن امتدادات الملفات لا تهمك على نظامَي التشغيل macOS وLinux، يمكنك دائمًا استخدام .bat كإضافة، حتى بالنسبة إلى نصوص واجهة المستخدم.

    يُرجى العلم أنه لا يمكن تنفيذ ملفات .bat الفارغة. إذا كنت بحاجة إلى نص برمجي فارغ، اكتب مسافة واحدة فيه.

  • استخدِم باشا بطريقة أساسية.

    في قواعد Starlark للإصدار والاختبار، يمكنك استخدام ctx.actions.run_shell لتنفيذ أوامر Bash وأوامر Bash الشخصية.

    في وحدات ماكرو Starlark، عليك لفّ النصوص البرمجية وأوامر Bash في native.sh_binary() أو native.genrule(). سيتحقّق Bazel مما إذا كان Bash متاحًا ويشغّل النص البرمجي أو الأمر من خلال Bash.

    في قواعد مستودع Starlark، حاوِل تجنُّب استخدام Bash تمامًا. لا يوفر Bazel حاليًا طريقة لتشغيل الأوامر الصوتية بطريقة أساسية في قواعد المستودع.

جارٍ حذف الملفات

المشاكل:

  • لا يمكن حذف الملفات أثناء فتحها.

    لا يمكن حذف الملفات المفتوحة (تلقائيًا)، وقد تؤدي المحاولات إلى ظهور أخطاء &quot،تم رفض الوصول&quot، . إذا لم تتمكن من حذف أحد الملفات، ربما لا تزال هناك عملية قيد التشغيل.

  • لا يمكن حذف دليل العمل الخاص بالعملية قيد التشغيل.

    تحتوي العمليات على اسم مفتوح لدليل العمل، ولا يمكن حذف الدليل حتى تنتهي العملية.

الحلول:

  • في الرمز، جرِّب إغلاق الملفات بحماس.

    في Java، استخدِم try-with-resources. في Python، استخدِم with open(...) as f:. من حيث المبدأ، حاول إغلاق المقابض في أقرب وقت ممكن.