Настройка вариантов публикации

Варианты публикации позволяют создать более индивидуальный подход для ваших пользователей. Настройка вариантов публикации позволяет публиковать различные варианты сборки, каждый со своими атрибутами.

Публикация нескольких вариантов сборки вашей библиотеки позволяет пользователю выбирать функции, соответствующие его потребностям. Например, вы можете публиковать разные артефакты для типов сборки отладки и выпуска . Артефакт публикации отладки может иметь дополнительный код ведения журнала и различные зависимости для включения этого дополнительного ведения журнала.

Прежде чем продолжить, убедитесь, что вы подготовили свою библиотеку к выпуску .

Используйте метаданные модуля Gradle

Чтобы опубликовать варианты вашей библиотеки, вы должны использовать метаданные модуля Gradle (GMM) . GMM описывает вашу публикацию и поддерживает управление зависимостями с учетом вариантов . GMM по умолчанию публикуется вместе с вашей библиотекой.

Преимущества использования GMM включают в себя:

• Если вы используете GMM с Gradle 6.0 или выше, вы можете публиковать несколько вариантов публикации или несколько артефактов — каждый со своими атрибутами и зависимостями. Если вы используете POM-файл Maven вместо GMM, вы можете опубликовать только один артефакт. Если вы используете файл POM, вы можете публиковать дополнительные артефакты с помощью классификаторов, но дополнительные артефакты не могут иметь собственных зависимостей.
• Gradle автоматически создает один вариант для компиляции и один для времени выполнения, каждый со своими зависимостями. Вы можете опубликовать один вариант для компиляции и один для среды выполнения, чтобы потребитель мог выбирать в зависимости от того, когда он использует вашу библиотеку. GMM позволяет потребителям видеть различные зависимости для компиляции и среды выполнения на основе использования опубликованной библиотекой api , implementation или compileOnly / runtimeOnly . Полный список зависимостей см. в разделе «Конфигурации зависимостей ». Это доступно, даже если вы публикуете один вариант публикации.
• При использовании тестовых приспособлений вы можете опубликовать дополнительный вариант со специальными метаданными или возможностями , которые позволят потребителю выбрать его. Это доступно, даже если вы публикуете один вариант публикации.

Ознакомьтесь с вариантами публикации

Чтобы понять, как работают варианты публикации, полезно ознакомиться с основными этапами публикации Gradle. Вот некоторые ключевые понятия публикации:

• Вариант сборки : конфигурация, которую Gradle использует для сборки вашей библиотеки, которая является перекрестным продуктом типа сборки и разновидности продукта. Дополнительную информацию см. в глоссарии сборок Android .
• Артефакт : файл или каталог, создаваемый сборкой. В контексте публикации библиотеки артефактом обычно является файл 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) для этих двух вариантов одинаковы.

Дополнительные сведения см. в документации API publishing .

Проблема совместимости при публикации многовариантных библиотек.

Проект, использующий AGP 7.0 или более раннюю версию, не может использовать библиотеки с несколькими вариантами, опубликованные с помощью AGP 7.1 или более поздней версии. Это известная проблема, вызванная изменением имени атрибута для измерения вкуса продукта с dimensionName на com.android.build.api.attributes.ProductFlavor:dimensionName в AGP 7.1. В зависимости от настроек вашего проекта вы можете использовать missingDimensionStrategy в старом варианте API, чтобы обойти эту проблему.

Например, предположим, что ваш проект приложения имеет только измерение версии продукта:

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)
    }
}