کتابخانه خود را برای انتشار آماده کنید

این صفحه ویژگی‌ها و گزینه‌های مورد نیاز برای آماده‌سازی پروژه کتابخانه اندروید شما برای انتشار با استفاده از افزونه Android Gradle (AGP) را شرح می‌دهد. حتی اگر برخی از این ویژگی‌ها را در ابتدای ایجاد کتابخانه خود تنظیم کرده‌اید، برای بهینه‌سازی تنظیمات خود، راهنمایی‌های زیر را مرور کنید.

انتخاب یک فضای نام

کتابخانه‌های اندروید باید یک فضای نام (namespace) تعریف کنند تا بتوانند هنگام کامپایل منابعشان، یک کلاس R منحصر به فرد تولید کنند. این فضای نام باید دقیقاً با بسته کلاس ریشه کتابخانه مطابقت داشته باشد تا از سردرگمی هنگام وارد کردن کلاس‌های معمولی از کتابخانه و کلاس R آن توسط کاربران جلوگیری شود.

با شروع از AGP 7.0، می‌توانید فضای نام را در فایل build.gradle برنامه تنظیم کنید، همانطور که در مثال کد زیر نشان داده شده است:

android {
  namespace = 'com.example.library'
}

android {
  namespace = "com.example.library"
}

فضای نام، یک ویژگی کتابخانه است که در دسترس توسعه‌دهندگان قرار دارد و به هویت برنامه که با استفاده از ویژگی applicationId تنظیم می‌شود، ارتباطی ندارد.

در نسخه‌های قبلی AGP، هم ویژگی applicationId (برای یک برنامه) و هم ویژگی namespace (برای یک کتابخانه) می‌توانستند با استفاده از ویژگی package در manifest تنظیم شوند، که منجر به سردرگمی می‌شد.

مقدار minSdkVersion را انتخاب کنید

انتخاب minSdkVersion برای کتابخانه‌تان، جنبه‌ی مهمی از انتشار کتابخانه‌تان است. minSdkVersion باید حداقل نسخه‌ی اندروید قابل پشتیبانی توسط کد شما را نشان دهد.

هنگام انتخاب minSdkVersion به نکات زیر توجه داشته باشید:

• انتخاب minSdkVersion پایین معمولاً امکان توزیع گسترده‌تر کتابخانه شما را فراهم می‌کند.

  کد یک کتابخانه معمولاً اجرا نمی‌شود مگر اینکه برنامه آن را صریحاً فراخوانی کند. یک برنامه همچنان می‌تواند با انجام بررسی‌های زمان اجرا قبل از فراخوانی کتابخانه، روی نسخه‌ای از اندروید که پایین‌تر از حد مورد نیاز وابستگی کتابخانه است - اگر کتابخانه برای عملکرد اصلی برنامه ضروری نباشد - اجرا شود. بنابراین، minSdkVersion کتابخانه خود را به اندازه‌ای پایین تنظیم کنید که بتوان آن را در برنامه‌ها تعبیه کرد و در صورت امکان فراخوانی کرد تا به دسترسی کاربران بیشتر کمک کند.

• انتخاب minSdkVersion بالا ممکن است مانع از گنجاندن کتابخانه در برنامه‌ها شود.

  ادغام مانیفست، که مرحله‌ای در AGP است که فایل‌های مانیفست را از برنامه و از وابستگی‌های آن ادغام می‌کند، تضمین می‌کند که هیچ وابستگی minSdkVersion بالاتری نسبت به برنامه نداشته باشد.

• انتخاب minSdkVersion بالا ممکن است توسعه‌دهندگان برنامه را وادار کند تا بررسی‌های ایمنی ادغام آشکار را غیرفعال کنند و بعداً در فرآیند ساخت مشکلاتی ایجاد کنند.

  از آنجا که ادغام مانیفست مانع از آن می‌شود که پروژه‌های برنامه، کتابخانه‌هایی با minSdkVersion بالاتر از خود برنامه را در خود جای دهند، توسعه‌دهندگان برنامه ممکن است بررسی‌های ایمنی ادغام مانیفست را غیرفعال کنند تا خطاهای ساخت را به حداقل برسانند. با این حال، این امر خطر مشکلات ناسازگاری واقعی را در مراحل بعدی به همراه دارد.

• انتخاب minSdkVersion بالا ممکن است در موارد خاصی که مانیفست یک کتابخانه شامل یک گیرنده پخش یا مکانیسم دیگری است که کد آن به طور خودکار فعال می‌شود، ضروری باشد.

  در این موارد، انتخاب minSdkVersion بالا تضمین می‌کند که کد می‌تواند اجرا شود. از طرف دیگر، می‌توانید رفتار خودکار را غیرفعال کنید تا برنامه بتواند پس از انجام بررسی‌های صحیح، اجرای کتابخانه را انتخاب کند.

برای اجازه دادن به جاسازی در برنامه‌ها، از حاشیه‌نویسی RequiresApi در کتابخانه خود استفاده کنید تا به فراخوانی‌کنندگان آن نشان دهید که باید بررسی‌های زمان اجرا را انجام دهند. Android Lint از اطلاعات RequiresApi برای بازرسی‌های خود استفاده می‌کند. برای منابع بیشتر در مورد استفاده از حاشیه‌نویسی‌ها برای بهبود کد API و APIهای خود، به بخش بهبود بازرسی کد با حاشیه‌نویسی‌ها مراجعه کنید.

تنظیم فراداده AAR

یک کتابخانه اندروید در قالب یک فایل بایگانی اندروید (AAR) بسته‌بندی می‌شود. فراداده‌های AAR شامل ویژگی‌هایی هستند که به AGP کمک می‌کنند تا کتابخانه‌ها را مصرف کند. اگر کتابخانه شما توسط یک پیکربندی ناسازگار مصرف شود و فراداده‌های AAR تنظیم شده باشند، به کاربران یک پیام خطا ارائه می‌شود تا به آنها در حل مشکل کمک کند.

مقدار minCompileSdk را انتخاب کنید

از نسخه ۴.۱ به بعد، AGP از minCompileSdk پشتیبانی می‌کند. این نشان دهنده حداقل compileSdk است که پروژه‌های در حال اجرا می‌توانند از آن استفاده کنند. اگر کتابخانه شما حاوی ورودی‌های مانیفست یا منابعی است که از ویژگی‌های پلتفرم جدیدتر استفاده می‌کنند، باید این مقدار را تنظیم کنید.

مقدار minCompileSdk را می‌توان در بلوک‌های defaultConfig{} ، productFlavors{} و buildTypes{} در فایل build.gradle سطح ماژول تنظیم کرد:

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

اگر minCompileSdk در چندین مکان تنظیم کنید، Gradle در طول فرآیند ساخت، مکان‌های تنظیمات را به شرح زیر اولویت‌بندی می‌کند:

1. buildTypes{}

2. productFlavors{}

3. defaultConfig{}

در مثال قبلی، که minCompileSdk هم در defaultConfig{} و هم در productFlavors{} تعریف شده است، productFlavors{} اولویت‌بندی شده و minCompileSdk روی 30 تنظیم شده است.

برای کسب اطلاعات بیشتر در مورد نحوه اولویت‌بندی تنظیمات توسط Gradle هنگام ترکیب کد و منابع، به Build with source sets مراجعه کنید.

فعال کردن ابزارهای تست

ابزارهای تست معمولاً برای تنظیم کدی که قرار است تست شود یا تسهیل تست‌های یک جزء استفاده می‌شوند. از نسخه ۷.۱ به بعد، AGP می‌تواند علاوه بر پروژه‌های کاربردی و پروژه‌های با ویژگی‌های پویا، ابزارهای تست را برای پروژه‌های کتابخانه‌ای نیز ایجاد کند.

هنگام انتشار یک کتابخانه برای استفاده دیگران، ایجاد ابزارهای تست برای API خود را در نظر بگیرید. ابزارهای تست را می‌توان در فایل build.gradle در سطح ماژول فعال کرد:

android {
  testFixtures {
    enable = true
  }
}

android {
  testFixtures {
    enable = true
  }
}

وقتی که ابزارهای تست را فعال می‌کنید، Gradle به طور خودکار یک مجموعه منبع src/testFixtures ایجاد می‌کند که می‌توانید ابزارهای تست را در آن بنویسید.

برای اطلاعات بیشتر، به مستندات Gradle در مورد استفاده از وسایل تست مراجعه کنید.