Ant'ı görselleştirme

Geçen gün Visualizing Data: Self-Documenting Ant files isminde bir yazı okudum... Ant scriptlerinin görsel olarak daha rahat anlaşılabilmesi için kullanılabilecek yöntemlerden bahsediyordu.. Üzerinde biraz düşündüğümde, yapılabilecek görsel bir sunumun ant'ı ne kadar anlamlı yapabileceğini rahatça söyleyebilirim. Bunun yanında okuması ve anlaması kolay olan Ant scriptleri bu scriptlerle çalışmayı da kolaylaştıracaktır.

Bununla ilgili kullanılabilecek yöntemleri; antpretty, ant'ın projecthelp özelliği, antdoc, ant2svg ve grand olarak belirtmişti yazar... Fakat benim en çok dikkatimi çeken AntDoc oldu.. Bu nedenle bu yazıda AntDoc'tan bahsedeceğim.

Öncelikle, AntDoc açık kaynak değil ama bedava, fakat uzun süredir geliştirilmiyor.. Dolayısıyla bunu hayata geçirdikten sonra ileride (belki güncellenmediğinden dolayı) vazgeçmek zorunda kalacağız, ama en azından dokümantasyon yapmış olacağız. Ve bu tür davranışlara bir kere alıştınız mı, bırakması çok zor olur.

Konumuza dönelim, JavaDoc hakikaten önemli bir kavram, hangi pakette, hangi sınıfların bulunduğunu, metodlarının neler olduğunu ve ne iş yaptığını bilmemiz açısından önemli. Bana göre yazılan koda biraz da hava katıyor. Tam anlamıyla kod olduğunu “bak bu da benim dokümantasyonum” diyerek kanıtlıyor. Bu noktada bizim en çok uğraştığımız konu olan ant scriptlerinin de buna benzer bir dokümantasyonunun olması normal olacaktır. Sistem büyüdükçe script sayısı artar, sirkülasyon devam ettikçe, herkese bunların ne iş yaptığını anlatmanız gerekir. Bunun yerine ant dokümantasyonu yaparsanız, herşey daha kolay olacaktır.

AntDoc'u hayata geçirmek için birkaç pakete ihtiyacımız var, bunlar Jakarta RegExp(1.5), Saxon(8.9 çalışmıyor, bunun yerine AntDoc download sayfasındaki 6.2.2 kullanmanız gerekiyor), JDOM(1.0), Log4j(1.2.15) ve AntDoc(0.8). Bu paketleri ANT_HOME altında lib klasörüne kopyalamamız başlamak için yeterli.

AntDoc'u kullanmak için öncelikle taskdef tanımını scriptimize eklememiz gerekiyor.

<taskdef name="AntDoc" classname="org.ed.pack.ant.AntDoc"/>

Ardından en basit haliyle aşağıdaki örnek task'ı scriptine eklemeniz Ant'ı dokümante etmeniz için yeterli olacaktır.

<antdoc destination="antdoc" buildfile="${ant.file}"></antdoc>

Bu task, antdoc klasörü altında, çalıştırılan ant dosyasının dokümantasyonunu HTML formatında hazırlayacaktır. AntDoc taskının özellikleri tabiiki bu kadar değil, filtering, filesetler ve daha bir çok özellik var. Ben sadece basitçe nasıl hayata geçirebileceğimizi anlatmaya çalıştım. Detaylı kullanım ile ilgili dokümantasyonu bu linkten bulabilirsiniz.

Bu noktada faydalı olabilecek birkaç önerim olacak;

• Ant dokümantasyonunu sürüm işlerinden ayrı bir şekilde yapmak istiyorsanız, bu taskı başka bir scripte koyup, buildfile dosyasına dokümante etmek istediğiniz ant scriptinin adını yazmanız yeterli.
  

• Bunu Sürekli Entegrasyon sistemine günlük çalışan bir ant işi olarak ekleyip işlerin otomatik çalışmasını sağlayabilirsiniz.
  

• Bunun yanında dokümantasyonun sadece ant scriptinde değişiklik olduğunda güncellenmesini istiyorsanız aşağıdaki ant scriptini kullanabilirsiniz.

<target name="DocumentAntScript" depends="antdoc.checkIfRequired" unless="antdocBuild.notRequired" description="build API documentation for build file">
<taskdef name="AntDoc" classname="org.ed.pack.ant.AntDoc">
<antdoc destination="antdoc" buildfile="${ant.file}">
</antdoc>

<target name="antdoc.checkIfRequired">
<uptodate property="antdocBuild.notRequired" targetfile="antdoc/index.html" srcfile="${ant.file}">
</uptodate></target></taskdef>
</target>

• Yukarıdaki blok, oluşturulan ant dokümantasyonu index.html dosyası ile ant scriptinin tarihlerini karşılaştırıp eğer script güncellendi ise dokümantasyonun oluşturulmasını sağlar.

Evet, ant scriptlerinizi dokümante etmeniz bu kadar kolay. Umarım yardımcı olur...