Skonfiguruj generowanie profilu podstawowego

Wtyczka Gradle Baseline Profile ułatwia generowanie i obsługę profili bazowych. Umożliwia to:

• Utwórz nowe profile podstawowe dla swojej aplikacji.
• Utwórz nowe profile podstawowe dla swojej biblioteki.
• Dostosuj generowanie profilu bazowego.

Na tej stronie dowiesz się, jak używać wtyczki Gradle profilu bazowego do dostosowywania generowania profili bazowych.

Wymagania dotyczące wtyczek

• AGP 8.0 lub nowszy
• Zależność od najnowszej wersji wtyczki Gradle

Generowanie profili podstawowych za pomocą urządzeń zarządzanych przez Gradle

Aby wygenerować profil podstawowy za pomocą zarządzanego przez Gradle urządzenia (GMD), dodaj go do konfiguracji build.gradle.kts modułu generującego profil, prawdopodobnie modułu testowego :baselineprofile, jak pokazano w tym przykładzie:

android {
   testOptions.managedDevices.devices {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           device = "Pixel 6"
           apiLevel = 31
           systemImageSource = "aosp"
       }
   }
}

android {
   testOptions.managedDevices.devices {
       pixel6Api31(ManagedVirtualDevice) {
           device 'Pixel 6'
           apiLevel = 31
           systemImageSource 'aosp'
       }
   }
}

Aby wygenerować profile podstawowe za pomocą GMD, dodaj go do konfiguracji wtyczki Gradle profilu podstawowego w ten sposób w build.gradle.kts modułu testowego :baselineprofile:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

Gdy używasz GMD do generowania profili podstawowych, ustaw useConnectedDevices na false w module testowym :baselineprofile:

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

Generowanie profili podstawowych dla różnych wariantów

Możesz wygenerować profile podstawowe dla każdego wariantu, każdego smaku lub jako jeden plik, który będzie można wykorzystać we wszystkich wariantach. Możesz kontrolować to działanie za pomocą ustawienia scalania, jak pokazano w poniższym przykładzie, w build.gradle.kts modułu aplikacji lub biblioteki.

baselineProfile {
    mergeIntoMain = true
}

baselineProfile {
    mergeIntoMain true
}

Aby scalić wygenerowane profile wszystkich wariantów w jeden profil, ustaw wartość parametru mergeIntoMain na true. Gdy to ustawienie jest włączone (true), nie można generować profili podstawowych dla poszczególnych wariantów, więc jest tylko jedno zadanie Gradle o nazwie generateBaselineProfile. Profil jest wyświetlany w src/main/generated/baselineProfiles.

Aby wyłączyć scalanie i mieć jeden profil na wariant, ustaw wartość mergeIntoMain na false. W tym przypadku istnieje wiele zadań Gradle dotyczących konkretnych wariantów. Na przykład jeśli są 2 wersje (bezpłatna i płatna) oraz 1 typ kompilacji wersji, zadania są następujące:

* `generateFreeReleaseBaselineProfile`
* `generatePaidReleaseBaselineProfile`
* `generateReleaseBaselineProfile`

Aby określić sposób scalania dla każdego wariantu, użyj tego kodu:

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

W powyższym przykładzie warianty, w których flaga ma wartość true, są scalane w src/main/generated/baselineProfiles, a profile wariantów, w których flaga ma wartość false, są przechowywane w folderze src/<variant>/generated/baselineProfiles.

Domyślnie w przypadku bibliotek ustawienie mergeIntoMain ma wartość true, a w przypadku aplikacji – false.

Automatyczne generowanie profili bazowych podczas tworzenia nowej wersji

Profile bazowe możesz skonfigurować tak, aby były generowane automatycznie przy każdej kompilacji wersji, zamiast ręcznie używać zadania generateBaselineProfile. Dzięki automatycznemu generowaniu w wersji do udostępnienia uwzględniany jest najbardziej aktualny profil.

Aby włączyć automatyczne generowanie w przypadku wersji produkcyjnych, użyj flagiautomaticGenerationDuringBuild:

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

Ustawienie flagi automaticGenerationDuringBuild na true powoduje wygenerowanie nowego profilu podstawowego dla każdego zestawu wersji. Oznacza to, że uruchomienie zadania kompilacji wersji do publikacji, takiego jak ./gradlew:app:assembleRelease, powoduje również uruchomienie :app:generateReleaseBaselineProfile, rozpoczęcie testów instrumentacji profilu bazowego i utworzenie kompilacji profilu bazowego, na której są one uruchamiane. Automatyczne generowanie pomaga użytkownikom uzyskać najlepsze wyniki, ale wydłuża czas kompilacji ze względu na podwójną kompilację i testy instrumentacji.

Możesz też określić to działanie dla każdej odmiany, jak pokazano w tym przykładzie:

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

W poprzednim przykładzie zadanie generateFreeReleaseBaselineProfile jest wykonywane po uruchomieniu assembleFreeRelease. Jest to przydatne, gdy użytkownik chce mieć np. kompilację release do dystrybucji, która zawsze generuje profil podczas kompilacji, oraz kompilację releaseWithoutProfile do testów wewnętrznych.

Zamiast dodawać nowy wariant bez profilu podstawowego, możesz też wyłączyć generowanie z wiersza poleceń w ten sposób:

./gradlew assembleRelease -Pandroid.baselineProfile.automaticGenerationDuringBuild=false

Przechowywanie profili podstawowych w źródłach

Profile bazowe możesz przechowywać w katalogu źródłowym za pomocą flagi saveInSrc w build.gradle.kts modułu aplikacji lub biblioteki:

• true: profil podstawowy jest przechowywany w src/<variant>/generated/baselineProfiles. Dzięki temu możesz zatwierdzić najnowszy wygenerowany profil ze swoimi źródłami.
• false: profil podstawowy jest przechowywany w plikach pośrednich w katalogu kompilacji. Dzięki temu podczas zatwierdzania kodu nie zapiszesz najnowszego wygenerowanego profilu.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

Możesz też określić to działanie dla każdego wariantu:

baselineProfile {
    variants {
        freeRelease {
            saveInSrc = true
        }
    }
}

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

Wyłączanie ostrzeżeń

Domyślnie wtyczka Gradle profilu podstawowego ostrzega o sytuacjach, które mogą powodować problemy. Aby wyłączyć ostrzeżenia, możesz ustawić odpowiednią opcję na false w pliku build.gradle.kts. Dostępne opcje ostrzeżeń:

baselineProfile {
    warnings {

        /**
        * Warn when the Android Gradle Plugin version is higher than the max
        * tested one.
        */
        maxAgpVersion = true

        /**
        * Warn when a benchmark or baseline profile variant has been disabled.
        */
        disabledVariants = true

        /**
        * Warn that running `generateBaselineProfile` with AGP 8.0 doesn't
        * support running instrumentation tests for multiple build types at
        * once.
        */
        multipleBuildTypesWithAgp80 = true

        /**
        * Warn when no baseline profiles are generated after running the
        * generate baseline profile command.
        */
        noBaselineProfileRulesGenerated = true

        /**
        * Warn when no startup profiles are generated after running the generate
        * baseline profile command.
        */
        noStartupProfileRulesGenerated = true
    }
}

Filtrowanie reguł profilu

Wtyczka Gradle profilu podstawowego umożliwia filtrowanie wygenerowanych reguł profilu podstawowego. Jest to szczególnie przydatne w przypadku bibliotek, jeśli chcesz wykluczyć reguły profilu dla klas i metod, które są częścią innych zależności aplikacji przykładowej lub samej biblioteki. Filtry mogą uwzględniać i wykluczać konkretne pakiety i klasy. Jeśli określisz tylko wykluczenia, wykluczone zostaną tylko pasujące reguły profilu podstawowego, a wszystkie pozostałe zostaną uwzględnione.

Specyfikacja filtrów może być dowolnym z tych elementów:

• Nazwa pakietu kończąca się podwójnymi symbolami wieloznacznymi, aby pasowała do określonego pakietu i wszystkich podpakietów. Na przykład com.example.** pasuje do com.example.method i com.example.method.bar.
• Nazwa pakietu kończąca się symbolem wieloznacznym, aby pasowała tylko do określonego pakietu. Na przykład wyrażenie com.example.* pasuje do wyrażenia com.example.method, ale nie do wyrażenia com.example.method.bar.
• Nazwy klas, które mają pasować do konkretnej klasy, np. com.example.MyClass.

Przykłady poniżej pokazują, jak uwzględniać i wykluczać konkretne pakiety:

baselineProfile {
    filter {
        include("com.somelibrary.widget.grid.**")
        exclude("com.somelibrary.widget.grid.debug.**")
        include("com.somelibrary.widget.list.**")
        exclude("com.somelibrary.widget.list.debug.**")
        include("com.somelibrary.widget.text.**")
        exclude("com.somelibrary.widget.text.debug.**")
    }
}

baselineProfile {
    filter {
        include 'com.somelibrary.widget.grid.**'
        exclude 'com.somelibrary.widget.grid.debug.**'
        include 'com.somelibrary.widget.list.**'
        exclude 'com.somelibrary.widget.list.debug.**'
        include 'com.somelibrary.widget.text.**'
        exclude 'com.somelibrary.widget.text.debug.**'
    }
}

Dostosuj reguły filtrowania dla różnych wariantów w ten sposób:

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include("com.myapp.**") }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include("com.myapp.free.**")
            }
        }
        paid {
            filter {
                include("com.myapp.paid.**")
            }
        }
    }
}

// Build-type-specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include 'com.myapp.**' }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include 'com.myapp.free.**'
            }
        }
        paid {
            filter {
                include 'com.myapp.paid.**'
            }
        }
    }
}

// Build-type specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

Reguły możesz też filtrować za pomocą argumentu filterPredicate w BaselineProfileRule.collect(), ale zalecamy używanie wtyczki Gradle do filtrowania, ponieważ zapewnia ona prostszy sposób filtrowania pakietów podrzędnych i jedno miejsce do konfigurowania całego modułu.

Dostosowywanie typów kompilacji profilu porównawczego i profilu podstawowego

Wtyczka Gradle profilu podstawowego tworzy dodatkowe typy kompilacji, aby generować profile i uruchamiać testy porównawcze. Te typy kompilacji mają prefiksy benchmark i nonMinified. Na przykład w przypadku typu kompilacji release wtyczka tworzy typy kompilacji benchmarkRelease i nonMinifiedRelease. Te typy kompilacji są automatycznie konfigurowane pod kątem konkretnego przypadku użycia i zwykle nie wymagają dostosowywania. W niektórych przypadkach może się jednak przydać zastosowanie opcji niestandardowych, np. innej konfiguracji podpisywania.

Możesz dostosować automatycznie generowane typy kompilacji, używając podzbioru właściwości typu kompilacji. Właściwości, których nie można użyć, są zastępowane. Poniższy przykład pokazuje, jak dostosować dodatkowe typy kompilacji i które właściwości są zastępowane:

android {
    buildTypes {
        release {
            ...
        }
        create("benchmarkRelease") {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default
            // it's the same as for the `release` build type).
            signingConfig = signingConfigs.getByName("benchmarkRelease")
        }
        create("nonMinifiedRelease") {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.getByName("nonMinifiedRelease")

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't
            // customize the following properties, which are always overridden to
            // avoid breaking Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false
        }
    }
}

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default it's the
            // same as for the `release` build type.)
            signingConfig = signingConfigs.benchmarkRelease
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.nonMinifiedRelease

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't use
            // the following properties, which are always overridden to avoid breaking
            // Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false       
        }
    }
}

Uwagi dodatkowe

Podczas tworzenia profili podstawowych pamiętaj o tych dodatkowych kwestiach:

• Skompilowane profile bazowe muszą być mniejsze niż 1,5 MB. Nie dotyczy to formatu tekstowego w plikach źródłowych, które przed kompilacją są zwykle znacznie większe. Sprawdź rozmiar binarnego profilu podstawowego, wyszukując go w artefakcie wyjściowym w folderze assets/dexopt/baseline.prof w przypadku pliku APK lub BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof w przypadku pakietu aplikacji na Androida.

• Przybliżone reguły, które kompilują zbyt dużą część aplikacji, mogą spowolnić uruchamianie z powodu zwiększonego dostępu do dysku. Jeśli dopiero zaczynasz korzystać z profili podstawowych, nie musisz się tym przejmować. Jednak w zależności od aplikacji oraz rozmiaru i liczby ścieżek dodanie wielu ścieżek może spowodować obniżenie wydajności. Sprawdź wydajność aplikacji, wypróbowując różne profile i upewniając się, że po dodaniu nowych elementów nie ulegnie ona pogorszeniu.

Codelabs