ضبط صيغ جهة النشر

تتيح لك متغيرات جهة النشر إمكانية توفير تجربة أكثر تخصيصًا للمستخدمين. يتيح لك ضبط صيغ جهة النشر نشر صيغ مختلفة للإصدارات، ولكل منها سماتها الخاصة.

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

قبل المتابعة، تأكد من تجهيز مكتبتك للإصدار.

استخدام البيانات الوصفية لوحدة Gradle

لنشر نُسخ مختلفة من مكتبتك، عليك استخدام البيانات الوصفية لوحدة Gradle (GMM). تصف "منصة Google للتسويق" جهة النشر الخاصة بك وتحافظ على إدارة التبعية الواعية للخيارات. يتم نشر خرائط Google للأجهزة الجوّالة (GMM) في مكتبتك بشكل تلقائي.

في ما يلي بعض مزايا استخدام "خرائط Google":

• إذا كنت تستخدم GMM مع Gradle 6.0 أو إصدار أحدث، يمكنك نشر صِيغ متعدّدة للنشر أو عناصر متعددة، لكلّ منها سماتها وتبعياتها الخاصة. إذا كنت تستخدم ملف POM من Maven بدلاً من GMM، يمكنك نشر عنصر واحد فقط. وإذا كنت تستخدم ملف POM، يمكنك نشر عناصر إضافية باستخدام المصنِّفات، ولكن لا يمكن أن يكون للأدوات الإضافية تبعيات خاصة بها.
• تنشئ Gradle تلقائيًا متغيرًا واحدًا للتجميع ومتغيرًا لوقت التشغيل، لكل منها تبعيات خاصة به. ويمكنك نشر صيغة واحدة للتجميع وآخر لوقت التشغيل، بحيث يمكن للمستهلك الاختيار بناءً على وقت استخدامه لمكتبتك. تتيح خدمة "خرائط Google" للمستهلكين الاطّلاع على تبعيات مختلفة للتجميع ووقت التشغيل، استنادًا إلى استخدام المكتبة المنشورة لـ api أو implementation أو compileOnly/runtimeOnly. راجِع إعدادات التبعية للحصول على قائمة كاملة بالتبعيات. وهي متاحة حتى في حال نشر إصدار واحد من جهة النشر.
• عند استخدام الأدوات الاختبارية، يمكنك نشر صيغة إضافية مع بيانات وصفية خاصة أو إمكانات تسمح للمستهلك باختيارها. وهي متاحة حتى إذا نشرت نسخة واحدة من جهة النشر

فهم صيغ جهة النشر

لفهم آلية عمل نُسخ جهات النشر، من المفيد أن تكون على دراية بالخطوات الأساسية للنشر في Gradle. في ما يلي بعض المفاهيم الأساسية لجهة النشر:

• إنشاء صيغة: الإعدادات التي تستخدمها Gradle لإنشاء مكتبتك، وهي منتج متقاطع لنوع التصميم ونكهة المنتج. لمعرفة المزيد من المعلومات، يمكنك الاطّلاع على مسرد مصطلحات إصدار Android.
• أداة Artifact: ملف أو دليل ينتج عن الإصدار. في سياق نشر المكتبة، يكون العنصر عادةً ملف JAR أو AAR.
• خيار جهة النشر: عنصر بسماته وميزاته وتبعياته المرتبطة به تجدر الإشارة إلى أنّ Gradle يُطلق على المتغيرات في جهات النشر الصيغ. وتُسمّى هذه الإصدارات إصدارات جهة النشر ضمن هذه المستندات لتمييزها عن إصدارات الإصدار.
• السمة: يستخدم تطبيق Gradle السمات لتحديد خيارات جهة النشر واختيارها عندما تتوفر خيارات متعددة. على سبيل المثال، org.gradle.usage=java-api وorg.gradle.jvm.version=11 هما سمتان لخيارات المنتج.
• مكوِّن البرنامج: كائن Gradle يمكن أن يحتوي على صيغة واحدة أو أكثر للنشر ويتم نشره على مجموعة واحدة من إحداثيات Maven (groupdId:artifactId:version). ويظهر في DSL من Gradle من خلال Project.getComponents().
• جهة النشر: العناصر التي يتم نشرها في المستودع والتي يستخدمها المستهلكون وتتكوّن جهات النشر من مكوّن برنامج واحد وبياناته الوصفية، مثل هويته (groupId:artifactId:version).

يقدّم مكوّن Android Gradle الإضافي (AGP) 7.1 لغة خاصة بالنطاق (DSL) بهدف التحكّم في صيغ الإصدار التي يتم استخدامها أثناء عملية النشر وتلك التي يتم تجاهلها. يتيح لك DSL إنشاء نسخ افتراضية من SoftwareComponent تحتوي على أي مما يلي:

• صيغة واحدة لجهة النشر من إصدار واحد
• عدة خيارات لجهات النشر من إصدارات متعدّدة

عند إنشاء مكوِّن برمجي بنُسخ متعدّدة من جهات النشر، تُعِدّ AGP سمات على كل صيغة تسمح للمستهلك بتحديد الخيار المناسب الذي يحتاجه. تأتي هذه السمات مباشرةً من نوع التصميم والنكهات المستخدمة لإنشاء متغير الإصدار. لا يتطلب إنشاء مكوِّن بمتغيّر واحد لجهة النشر توفّر سمات لأنّه لا حاجة إلى التفرقة بينها.

إنشاء مكوِّن برمجي باستخدام صيغة جهة نشر واحدة

يضبط المقتطف التالي مكون برنامج باستخدام صيغة جهة نشر واحدة يتم إنشاؤها من صيغة الإصدار release ويضيف JAR المصدر كعنصر ثانوي:

android {
  publishing {
    singleVariant("release") {
        withSourcesJar()
    }
  }
}

android {
  publishing {
    singleVariant('release') {
        withSourcesJar()
    }
  }
}

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

إنشاء مكوِّن برمجي بنُسخ متعددة من جهات النشر

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

لنشر جميع صيغ الإصدار في مكوِّن واحد، حدِّد allVariants() في المجموعة multipleVariants{} ضمن ملف build.gradle على مستوى الوحدة:

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

يؤدي هذا إلى إنشاء مكوِّن واحد يُسمى default. لتسمية المكون شيئًا آخر، استخدم multipleVariants({name}). في هذه الحالة، يتم استخدام جميع أبعاد نوع التصميم ونكهة المنتج كسمات.

ويمكنك أيضًا اختيار الصيغ التي يتم نشرها باستخدام includeBuildTypeValues() وincludeFlavorDimensionAndValues():

android {
  publishing {
    multipleVariants("custom") {
      includeBuildTypeValues("debug", "release")
      includeFlavorDimensionAndValues(
        dimension = "color",
        values = arrayOf("blue", "pink")
      )
        includeFlavorDimensionAndValues(
          dimension = "shape",
          values = arrayOf("square")
      )
    }
  }
}

android {
  publishing {
    multipleVariants('custom') {
      includeBuildTypeValues('debug', 'release')
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'color',
        /*values =*/ 'blue', 'pink'
      )
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'shape',
        /*values =*/ 'square'
      )
    }
  }
}

في هذا المثال، يحتوي المكوِّن المخصّص على جميع مجموعات (debug وrelease) لنوع الإصدار و(blue وpink) للسمة color و (square) للسمة shape .

يجب إدراج جميع أبعاد النكهة، حتى إذا كنت تنشر قيمة واحدة فقط من سمة معيّنة، حتى يعرف AGP القيمة التي يجب استخدامها لكل بُعد.

يسرد الجدول التالي خيارات جهة النشر الناتجة والسمات المرتبطة بها.

من الناحية العملية، يتم نشر المزيد من خيارات المنتج. على سبيل المثال، يتم نشر كل متغير من المتغيرات أعلاه مرتين، إحداهما للتجميع والأخرى لوقت التشغيل، مع تبعيات مختلفة (بناءً على ما إذا كانت التبعيات المُعلَنة تستخدم implementation أو api) وبقيمة مختلفة للسمة org.gradle.Usage. ومع ذلك، فإن العناصر (ملف AAR) لهاتين المتغيرات هي ذاتها.

لمزيد من المعلومات، اطّلِع على مستندات واجهة برمجة التطبيقات publishing.

مشكلة التوافق عند نشر مكتبات متعددة النكهات

ولا يمكن للمشروع الذي يستخدم الإصدار 7.0 من AGP أو أقل استهلاك مكتبات متعددة النكهات تم نشرها باستخدام الإصدار 7.1 من AGP أو إصدار أعلى. هذه مشكلة معروفة ناتجة عن تغيير في اسم السمة لسمة نكهة المنتج من dimensionName إلى com.android.build.api.attributes.ProductFlavor:dimensionName في 7.1 جنيه مصري. وبناءً على إعداد مشروعك، يمكنك استخدام missingDimensionStrategy في واجهة برمجة التطبيقات للصيغة القديمة لحلّ هذه المشكلة.

على سبيل المثال، لنفترض أن مشروع تطبيقك يحتوي فقط على بُعد نكهة منتج الإصدار:

android {
    applicationVariants.forEach { variant ->
        val flavor = variant.productFlavors[0].name
        val attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        val dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}

android {
    applicationVariants.forEach { variant ->
        def flavor = variant.getProductFlavors()[0].name
        def attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        def dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}