Asystent uaktualniania wtyczki Androida Gradle (AGP) to narzędzie w Androidzie Studio, które pomaga uaktualnić wersję AGP używaną przez projekt.
Często publikujemy zmiany AGP związane z nowymi funkcjami konfigurowania kompilacji, nowymi interfejsami API do użytku przez inne wtyczki Gradle i ulepszeniami integracji kompilacji projektu z Androidem Studio. Uaktualnienie wersji AGP używanej przez projekt pozwala korzystać z najnowszych funkcji.
Więcej informacji o zalecanej strukturze projektu dla Asystenta uaktualniania znajdziesz w sekcji Konfiguracja na tej stronie.
Przypadki użycia Asystenta uaktualniania AGP
Asystent uaktualniania AGP przeprowadzi Cię przez zmiany wymagane do uaktualnienia wersji AGP. Oto najczęstsze przypadki użycia Asystenta uaktualniania:
Zmiany w składni: Asystent uaktualniania próbuje przetłumaczyć pliki kompilacji starszej wersji AGP na pliki potrzebne w nowszej wersji AGP. W miarę rozwoju AGP pliki kompilacji są aktualizowane, aby obsługiwać interfejsy, które z czasem są zastępowane, wycofywane lub przestają być obsługiwane.
Wymagania dotyczące zgodności AGP i Gradle: Asystent uaktualniania zna wymagania dotyczące zgodności AGP i Gradle i pomaga upewnić się, że używasz wersji Gradle wymaganej w przypadku Twojej wersji AGP.
Wymagania dotyczące zgodności między AGP a wtyczkami Gradle innych firm: Asystent uaktualniania zna wymagania dotyczące zgodności między AGP a niektórymi wtyczkami Gradle innych firm i pomaga w używaniu wersji wtyczek Gradle innych firm, które są wymagane w przypadku Twojej wersji AGP.
Asystent uaktualniania ułatwia aktualizowanie plików kompilacji i analizowanie powiązanych komunikatów o błędach po uaktualnieniu AGP. Asystent uaktualniania wyjaśnia też, dlaczego proponowane zmiany są konieczne.
Jak korzystać z Asystenta uaktualniania AGP
Aby użyć Asystenta uaktualniania, upewnij się, że struktura projektu jest zgodna z tym narzędziem, a następnie uruchom je w Android Studio zgodnie z opisem w sekcji Uruchamianie Asystenta uaktualniania.
Konfigurowanie projektu
Zanim uruchomisz Asystenta uaktualniania, upewnij się, że projekt jest prawidłowo sformatowany i ma kopię zapasową. Aby mieć pewność, że Asystent uaktualniania AGP jest prawidłowo skonfigurowany, zapoznaj się z poniższymi sekcjami.
Strukturyzowanie projektu za pomocą plików kompilacji Gradle i języka specyficznego dla domeny
Aby w pełni wykorzystać możliwości Asystenta uaktualniania AGP, wykonaj te czynności:
- Skonfiguruj kompilację za pomocą plików kompilacji Gradle: Asystent uaktualniania korzysta ze statycznej analizy plików kompilacji Gradle. Aby w pełni wykorzystać możliwości Asystenta uaktualniania, skonfiguruj kompilację za pomocą tych plików kompilacji. Użyj katalogów wersji Gradle, aby odwoływać się do zależności i wtyczek zdefiniowanych w pliku
libs.versions.tomlw podkatalogugradleprojektu.
- Używaj deklaratywnego języka DSL kompilacji: pliki kompilacji Gradle są wyrażone w języku Groovy lub Kotlin. Im bardziej deklaratywne jest wyrażenie konfiguracji projektu, tym większe prawdopodobieństwo, że Asystent uaktualniania znajdzie wszystkie miejsca, które wymagają dostosowania do uaktualnienia.
Nawet jeśli projekt spełnia te ograniczenia, Asystent uaktualniania może nie być w stanie przeprowadzić czystej aktualizacji. W artykule Rozwiązywanie problemów znajdziesz wskazówki dotyczące rozwiązywania błędów i zgłaszania ich.
Tworzenie kopii zapasowej projektu
Zanim użyjesz Asystenta uaktualniania, sprawdź, czy w projekcie nie ma żadnych niezatwierdzonych zmian (zgodnie z informacjami w systemie kontroli wersji). Jeśli nie korzystasz z systemu kontroli wersji, użyj w tym momencie kopii zapasowej ostatniej znanej prawidłowej wersji.
Po uruchomieniu Asystenta uaktualniania i pomyślnym utworzeniu oraz przetestowaniu projektu możesz zatwierdzić nową wersję projektu w systemie kontroli wersji.
Uruchom Asystenta uaktualniania
Aby uruchomić Asystenta uaktualniania, wykonaj te czynności:
Aby uruchomić Asystenta uaktualniania, otwórz Narzędzia > Asystent uaktualniania AGP lub kliknij powiadomienie, jak pokazano na rysunku 1.
W wyświetlonym oknie narzędzi zobaczysz szczegóły domyślnego uaktualnienia, w tym bieżącą wersję AGP projektu i najnowszą wersję obsługiwaną przez tę wersję Androida Studio.
Rysunek 1. Okno narzędzia Asystent uaktualniania AGP uruchomione z poziomu powiadomienia. Sprawdź wymagane i zalecane czynności.
W panelu po lewej stronie znajduje się drzewo z polami wyboru, które zawiera szczegółowe informacje o poszczególnych etapach uaktualniania, podzielone na kategorie w zależności od tego, czy są wymagane, czy zalecane, oraz czy są warunkiem wstępnym innych etapów. Wybierz poszczególne elementy w drzewie, aby wyświetlić więcej szczegółów o każdym kroku w panelu głównym.
Aby przeprowadzić uaktualnienie, wybierz wymagane i pożądane kroki, a następnie kliknij Uruchom wybrane kroki.
Asystent uaktualniania zmienia pliki kompilacji projektu i próbuje zsynchronizować nową kompilację projektu z Androidem Studio. Jeśli masz wiele modułów, może to potrwać dłużej, ponieważ konieczne może być pobranie nowych wersji wtyczek i bibliotek.
Sprawdź raport po uaktualnieniu. Ten raport zawiera opis wykonanych czynności oraz informację o tym, czy uaktualnienie się powiodło. Obejmuje też działanie, które umożliwia przywrócenie zmian wprowadzonych przez asystenta uaktualniania, jeśli po uaktualnieniu wystąpią problemy z kompilacją lub testowaniem projektu.
Gdy projekt zostanie zsynchronizowany z Androidem Studio, skompiluj go i uruchom pakiety testów, aby sprawdzić, czy operacja uaktualnienia nie zmieniła żadnej funkcji.
Po sprawdzeniu, czy projekt jest w dobrym stanie, zatwierdź nową wersję projektu w systemie kontroli wersji.
Rozwiązywanie problemów
Jeśli Asystent uaktualniania sugeruje uaktualnienie, ale uaktualnienie się nie powiedzie, zwykle jest to spowodowane wprowadzeniem zmian w plikach kompilacji, co powoduje niepowodzenie synchronizacji. Aby znaleźć i naprawić błąd, wykonaj te czynności:
Najpierw sprawdź błąd, który spowodował niepowodzenie synchronizacji. Czasami błąd ma oczywistą przyczynę, którą można rozwiązać w plikach kompilacji projektu.
Jeśli komunikat o błędzie jest niejasny lub nie wiesz, co powoduje problem, przywróć projekt do pierwotnego stanu, aby podzielić uaktualnianie na mniejsze kroki. Przywróć pierwotny stan z systemu kontroli wersji lub z kopii zapasowych i upewnij się, że projekt jest w pierwotnym stanie i zsynchronizowany z Androidem Studio.
Zbadaj błąd, korzystając z 2 rodzajów podziałów uaktualnienia:
Uaktualnij do innej wersji AGP, która nie jest najnowsza. Jeśli nieudane uaktualnienie obejmowało dużą liczbę wersji, najlepszym sposobem na wyizolowanie problemu jest przeprowadzenie serii mniejszych uaktualnień, od wersji do wersji, aby znaleźć pierwsze uaktualnienie, które powoduje problem.
W ramach uaktualnienia wykonuj poszczególne czynności pojedynczo. Gdy ustalisz, które uaktualnienie powoduje problem, możesz wyłączyć poszczególne kroki uaktualnienia. Jeśli to możliwe, wykonuj poszczególne kroki po kolei, aby sprawdzić, który z nich powoduje błąd. Jeśli nie możesz znaleźć odpowiedzialnego za to kroku, sprawdź informacje o wersji innych używanych wtyczek Gradle pod kątem problemów ze zgodnością z Gradle lub AGP. Czasami nowa wersja dotyczy używania wycofanych lub wewnętrznych interfejsów API.
Zgłoś błąd. Czasami wszystkie kroki przygotowawcze i synchronizacja przebiegają pomyślnie, ale ostatni krok aktualizacji kończy się niepowodzeniem. W takim przypadku zgłoś błąd. Nawet jeśli uda Ci się samodzielnie naprawić błąd, zgłoś pierwotną awarię w narzędziu do śledzenia błędów, aby zespół programistów mógł rozwiązać ten problem.