14 lipca 2008

Klasyfikatory w Maven 2 oraz polonizacja NetBeans IDE

Już jakiś czas minął od zgłoszenia usprawnienia związanego z niedostępnością dokumentacji javadoc w dystrybucji Apache Wicket (WICKET-1587 Include javadoc in the distro). Okazało się, że właśnie dzisiaj zamknięto moje zgłoszenie jako Duplicate ze wskazaniem na kolejne zgłoszenie WICKET-543 need javadocs embedded in the Wicket 1.3 zip file. W WICKET-543 zgłoszenie kończy się wskazaniem na plik dokumentacji w publicznym repozytorium mavenowym Wicketa - http://repo1.maven.org/maven2/org/apache/wicket/wicket. Wystarczy, więc pobrać dokumentację javadoc (lub jeszcze lepiej kodów źródłowych, które są tam również umieszczone) i sprawa wydaje się zamknięta.

W/g mnie nie rozwiązuje to głównego problemu niedostępności dokumentacji w samej paczce dystrybucyjnej Wicketa, bo nie wszyscy przecież korzystają z Mavena do zarządzania projektami, a nawet pracując z nim można nie zorientować się, gdzie jest dostępna dokumentacja do pobrania. Może jest to jednak efekt "nowych" czasów, gdzie jeśli nie korzystasz z Mavena toś...i tu należałoby umieścić coś niestosownego, bo przecież każdy wie jak z niego korzystać, albo jak pobrać plik z jego repozytorium. Nieprawdaż?! Ja jednak należę do tych (nie)szczęśników, którzy zazwyczaj pracują z Mavenem, jeśli idzie o zestawianie projektów poza IDE, więc mogę przychylić się do tego rozwiązania jako satysfakcjonujące. W Eclipse dostępna jest wtyczka m2eclipse, która umożliwia pobranie źródeł dla zadanych zależności (Maven > Download Sources), ale już w NetBeans mimo, dostępności wtyczki Mavenide-NetBeans, nie znalazłem podobnej funkcjonalności. Pozostaje rozpoznać temat z poziomu linii poleceń i zdefiniować odpowiednie polecenie dla NetBeans, bądź innego IDE w użyciu, jeśli dedykowane menu nie istnieje.

Rozróżnienie artefaktów pochodzących z pojedyńczego projektu (modułu) odbywa się z użyciem klasyfikatora (ang. classifier), które jest kolejnym elementem rozróżniania artefaktów w Maven 2 zgodnie z zasadą nazewniczą przedstawioną w rozdziale POM Relationships. Najbardziej powszechnym użyciem klasyfikatora to wskazanie pliku z dokumentacją javadoc (klasyfikator: javadoc) oraz źródłami (klasyfikator: sources). Deklaracja zależności w projekcie mavenowym odbywa się w pliku pom.xml, np.:
 <dependencies>
<dependency>
<groupId>org.apache.wicket</groupId>
<artifactId>wicket</artifactId>
<version>1.4-m3</version>
</dependency>
</dependencies>
i dotyczy zazwyczaj artefaktów, które są plikami jar (domyślna wartość dla elementu dependency/type to jar) z pustym klasyfikatorem. Wskazanie na zasób (artefakt) o klasyfikatorze javadoc wymaga skorzystania z elementu classifier z wartością javadoc. Pytanie, które należy w tym momencie zadać, to przypadek użycia, w którym chcielibyśmy skorzystać z możliwości zadeklarowania zależności projektu od klasyfikatora javadoc czy sources (pozostałe klasyfikatory pozostawiam do własnego przemyślenia). Dla przypadku wyłącznego pobrania javadoc czy źródeł z centralnego repozytorium Mavena korzysta się z pomocy dodatkowego parametru konfiguracyjnego wtyczki, która umożliwia skorzystanie z danego typu klasyfikatora (udostępnia rozwiązanie przypadku użycia, w którym dany klasyfikator gra znaczącą rolę).

Weźmy jako przykład pracę z javadoc. Jeśli chciałbym skorzystać z javadoc do umieszczenia jej w dystrybucji mojego projektu skorzystam z wtyczki maven-assembly-plugin, która potrafi "złożyć" plik wynikowy paczki dystrybucyjnej projektu, potencjalnie z dołączeniem dokumentacji javadoc dla wybranej zależności. W przypadku korzystania z dokumentacji javadoc czy źródeł w środowisku Eclipse wtyczka maven-eclipse-plugin generująca definicję projektu eclipsowego na podstawie pom.xml pozwala na określenie wymagania podpięcia javadoc czy źródeł do projektu - parametry -DdownloadJavadocs=true i -DdownloadSources=true, odpowiednio (patrz Attach Library Sources and Javadocs).

Wniosek jest jeden: w zależności od wymagań zazwyczaj nie przyjdzie Tobie skorzystanie z artefaktu o zadanym klasyfikatorze bezpośrednio, a raczej pośrednio, poprzez zależność w pom.xml czy konfigurację wtyczki. Jeśli jednak potrzebujemy pobrać pojedyńczy plik z repozytorium mavenowego, np. z dokumentacją javadoc, wystarczy skorzystać z wget czy podobnego narzędzia. To jednak sprowadza temat do bardzo znanej i lubianej kwestii doboru właściwego narzędzia do danego zadania. Kwesię obsługi javadoc w projekcie mavenowym zdaje się, że mam(y) rozwiązaną.

Kiedy teraz przyjdzie mi pracować z projektem mavenowym w środowisku Eclipse bez pomocy wtyczki m2eclipse wystarczy uruchomić polecenie
 mvn eclipse:eclipse -DdownloadSources=true  -DdownloadJavadocs=true
i zaimportować projekt, aby móc cieszyć się z pomocy kontekstowej javadoc oraz możliwości przejścia do kodów źródłowych dla klas zależności projektowej. Warto było zgłosić usprawnienie do Wicketa, aby w końcu rozpoznać to wszystko. Teraz już wszystko powinno być jasne.

Od kilku dobrych miesięcy trwają prace nad polonizacją NetBeans IDE 6. Prace trwają i mimo nadchodzącej wersji NetBeans IDE 6.5 (od 14-tego rozpoczynają się prace w NetCAT 6.5), wciąż nie ma produkcyjnej wersji NetBeans w języku polskim. Jeśli jesteś zainteresowany/-a posiadaniem spolszczonego NetBeansa i chciał(a)byś mieć swój udział w projekcie tłumaczenia przyłącz się do zespołu polonizującego NetBeans. Proponuję zacząć już dzisiaj.