Manual introdutrio do Apache ANT

Escrito por Alexandro Strack (alexandrostrack@hotmail.com)

Manual introdutrio do Apache ANT

Contedo
1- Introduo................................................................................................................................................... 3 1.1- Viso Geral......................................................................................................................................... 3 1.2- Histria................................................................................................................................................3 2- Instalao.................................................................................................................................................... 4 2.1- Obtendo o ANT ................................................................................................................................. 4 2.2- Instalando o ANT................................................................................................................................4 2.3- Configuraes adicionais.................................................................................................................... 5 2.4- Testando a instalao.......................................................................................................................... 5 3- Usando o Ant.............................................................................................................................................. 7 3.1- Estrutura do arquivo de build..............................................................................................................7 3.1- Estrutura do arquivo de build..............................................................................................................7 3.2- Principais elementos do arquivo build................................................................................................8 3.2.1- Projects (<project ...>).................................................................................................................8 3.2.2- Targets (<target...>).....................................................................................................................9 3.2.3- Tasks......................................................................................................................................... 11 3.2.4- Properties.................................................................................................................................. 11 3.2.5- Exemplo de um build completo................................................................................................ 13 4- Rodando o ANT....................................................................................................................................... 14 4.1- A partir da linha de comandos.......................................................................................................... 14 4.2- Integrado com IDEs.......................................................................................................................... 15 4.2.1- Eclipse....................................................................................................................................... 15 4.2.2- Oracle Jdeveloper......................................................................................................................18 5- Ant Tasks.................................................................................................................................................20 5.1- Compilao....................................................................................................................................... 21 5.2- Operaes com arquivos................................................................................................................... 23 5.3- Empacotamento e compresso..........................................................................................................26 5.4- Gerando documentao.....................................................................................................................29 5.5- Acesso remoto...................................................................................................................................30 6- Conceitos e Tipos..................................................................................................................................... 33 6.1- Conceitos.......................................................................................................................................... 33 6.2- Tipos................................................................................................................................................. 34 6.2.1- Descrio (description)............................................................................................................. 34 6.2.2- Operaes com estruturas de diretrios.................................................................................... 34 6.2.3- PatternSet.................................................................................................................................. 36 6.2.4- FileSet....................................................................................................................................... 37 6.2.5- DirSet........................................................................................................................................ 38 6.2.6- FilterSet..................................................................................................................................... 39 6.2.7- Selectors.................................................................................................................................... 40 7- Como criar uma nova task ....................................................................................................................... 43 8- Prximos passos....................................................................................................................................... 45

Manual introdutrio do Apache ANT

1- Introduo 1.1- Viso Geral

O ANT uma ferramenta destinada a construo (build) de programas JAVA. semelhante a ferramentas como make, nmake, jam mas com o diferencial de ser multi-plataforma, pois feita em JAVA. Atualmente considerada como padro de mercado para a criao de aplicaes JAVA. Um importante diferencial do ANT a sua capacidade de ser extendido atravs da definio de novas tarefas, escritas tambm em JAVA. Desta forma, o desenvolvedor no est limitado a apenas o conjunto de tarefas pr-existentes no ANT ficando livre para incorporar as tarefas que julgar necessrio. Sendo assim, possvel que um mesmo arquivo de build seja utilizado em mltiplas plataformas sem necessitar de qualquer tipo de modificao.

1.2- Histria
O ANT nasceu a partir do projeto TOMCAT, onde era mais um componente. Aps a doao do TOMCAT para o Apache Software Foundation (ocupando especificamente um lugar na rea de projetos do Apache Jakarta) foi descoberta a grande utilidade do ANT. Neste momento o ANT se desvinculou do TOMCAT tornando-se um projeto independente e ocupando tambm um lugar na rea de projetos do Apache Jakarta. Sua primeira verso independete nasceu em Julho de 2000. O nome ANT uma sigla para another neat tool (mais uma ferramenta organizada), segundo seu autor James Duncan Davidson.

Manual introdutrio do Apache ANT

2- Instalao 2.1- Obtendo o ANT

O ANT deve ser baixado atravs do seu web site em http://jakarta.apache.org/ant/ utilizando-se sempre a ltima verso estvel (no momento de escrita deste manual a verso mais estvel era 1.6.1). Esta verso suportada pelo JDK 1.1 ou superiores (recomenda-se no mnimo 1.2). Conforme dito anteriormente o ANT uma ferramenta escrita em JAVA e portanto necessita de no mnimo um JRE (Java Runtime Environment) executvel para que funcione. Vale lembrar que tendo apenas a JRE instalada muitos dos recursos do ANT no funcionaro. Sendo assim, recomendamos que voc tenha instalado um JDK completo (de preferncia a ltima verso estvel disponvel no site da SUN http://java.sun.com/getjava ).

2.2- Instalando o ANT

A verso de instalao do ANT distribuda em um arquivo compactado no formato ZIP. Aps a descompactao do arquivo de distribuio a estrutura de diretrios do ANT ficar assim:

Se a instalao for em ambiente WINDOWS recomenda-se que no sejam utilizados caminhos que possuam nomes longos, devido a uma limitao do sistema de batch destes sistemas operacionais. O ideal utilizar caminhos curtos, tradicionais, na forma 8.3 (8 caracteres para o nome e 3 para a extenso) e sem espaos em braco. Sugesto: c:\ant Evite: c:\java tools\ant (devido ao espao em branco entre java e tools).

Manual introdutrio do Apache ANT

2.3- Configuraes adicionais

Antes que se possa utilizar o ANT necessrio configurar algumas variveis de ambiente, a saber: PATH: inclua o caminho ant/bin s demais entradas j existentes. ANT_HOME: crie uma varivel de ambiente com este nome contendo o diretrio onde foi instalado o ant. Ex.: ANT_HOME=c:\ant JAVA_HOME: opcional. Entretanto para que se possa executar as tarefas baseadas na JDK como javac, jar, etc, importante que a biblioteca classes.jar ou tools.jar (dependendo da sua verso da JDK) seja encontrada. Isto somente ocorrer se a varivel JAVA_HOME existir e estiver corretamente configurada, isto , apontando para o diretrio de instalao da sua JDK. Ex.: JAVA_HOME=C:\j2sdk1.4 .

2.4- Testando a instalao

Para que voc possa se assegurar de que a instalao foi bem sucedida e que possui a ferramenta pronta para uso faa o seguinte teste:

Utilizando a tela de console de comandos digite: ant version. O resultado dever ser como o da tela abaixo (dependendo da verso que voc tem instalada).

Manual introdutrio do Apache ANT

Outra forma de se fazer o teste , tambm atravs da tela de console de comandos, digitando-se apenas: ant. O resultado deve ser como o visto na tela abaixo.

No caso de algum dos testes acima falhar ento voc dever rever os passos de instalao descritos acima. Principalmente se o seu ambiente for Windows, onde os nomes extensos so causadores de uma grande parte das falhas de instalao do ANT. Outro ponto importante que deve ser revisto a criao das variveis de ambiente pois sem elas realmente no funcionar.

Manual introdutrio do Apache ANT

3- Usando o Ant 3.1- Estrutura do arquivo de build

O arquivo utilizado pelo ANT para o build da aplicao um arquivo texto escrito em XML. Normalmente esse arquivo se chama build.xml (mas pode ter qualquer outro nome). Os elementos XML que compem este arquivo devem fazer parte do conjunto de elementos que o ANT entende, mas novos elementos podem ser facilmente criados (veremos como fazer isso mais adiante neste manual). O arquivo de build consiste basicamente de um elemento project que, por sua vez, contm um ou mais elementos target. Um target caracteriza uma das etapas que sero executadas na construo (build) da aplicao. Estas etapas so constitudas, por exemplo, pela compilao, empacotamento, distribuio, etc. Em cada uma destas etapas uma ou vrias operaes so executadas. Estas operaes so definidas por outros elementos XML que sero detalhados mais adiante. possvel que toda a construo (build) seja feita atravs de uma nica etapa (target). Entretando isto reduz de forma dramtica a possibilidade de reutilizao de partes do build, que muitas vezes so suficientes para resolver problemas pontuais. Sendo assim, comum dividir as etapas em subetapas menores (inclusive com nveis de dependncia uma das outras) onde cada etapa possui apenas o nmero de operaes suficientes para concluir o objetivo a que se destina. O elemento de mais alto nvel, project, deve informar qual ser o target padro a ser executado, caso nenhum seja informado no momento em que se rode o ANT. Vejamos abaixo um exemplo bsico de um arquivo build:
<?xml version="1.0"?> <project default="init"> <target name="init"> </target> </project>

Como todo arquivo XML, possvel utilizar um elemento que no possua subelementos atravs de sua declarao simplificada. Ou seja, no exemplo acima o elemento target poderia ser escrito da seguinte forma:

<target name="init"/>

Manual introdutrio do Apache ANT

3.2- Principais elementos do arquivo build

Conforme vimos no tem anterior o arquivo de build segue uma estrutura bem definida de elementos XML. Para que se possa criar os builds de forma eficiente necessrio conhecer os detalhes de seus principais elementos. Ento vamos a eles.

3.2.1- Projects (<project ...>)

Todo arquivo build deve conter um elemento project, afinal a construo de uma aplicao um projeto com objetivo bem definido. Desta forma temos que identificar neste projeto qual a tarefa (target) padro, ou seja, aquela que no pode deixar de ser executada caso nenhuma outra seja especificada no momento de execuo do ANT. Alm disso interessante que seja descrito o objetivo deste projeto e isso pode ser feito diretamente no prprio elemento project, atributo name, ou atravs de um elemento especfico para descries, description.
<project name=... default=... basedir=...> </project>

Atributo Descrio name Nome do Projeto. Pequena descrio do objetivo deste projeto. default Nome da tarefa padro (target) que dever ser executada caso nenhuma outra seja especificada no momento de execuo do ANT. basedir Diretrio base de onde todos os demais paths so derivados. Caso no seja informado ento o diretrio onde se encontra o arquivi build.xml assumido como diretrio base.

Obrigatrio No Sim No

Manual introdutrio do Apache ANT

Exemplos:
<project default=init> ... </project> <project name=Projeto de Exemplo default=doIT> ... </project> <project default=init basedir=/src> ... </project> <project name=Projecto de exemplo. default=init> <description> Projeto de exemplo com uma descrio mais detalhada usando o elemento description. </description> </project>

3.2.2- Targets (<target...>)

Para que seja feito um build necessrio definir as tarefas que sero executadas. Estas tarefas recebem o nome de target no ANT. Uma tarefa composta de operaes (so as chamadas tasks, como ser visto logo a seguir). Estas tarefas podem depender umas das outras e esta organizao de dependncia torna cada uma das tarefas mais reutilizvel. Atravs da dependncia se garante tambm que uma tarefa somente ser executada depois que suas dependentes tenham sido resolvidas. Para definir uma dependncia se utiliza o atributo depends. Atravs da definio de dependncia se consegue garantir uma ordem de execuo das tarefas, mas isso no significa que a execuo ser exatamente na ordem em que a dependncia est definida. Vamos a um exemplo:
<target name="A"/> <target name="B" depends="A"/> <target name="C" depends="B"/> <target name="D" depends="C,B,A"/>

A execuo da tarefa B depende da A e logo ser executada depois que A termine. Entretanto a tarefa D, que depende de C, B e A, ser executada depois da tarefa C pois C j depende de B, que por sua vez depende de A. Sendo assim no se faz necessrio executar as tarefas B e A de que D depende pois as mesmas j foram executadas indiretamente. Ou seja, uma tarefa executada somente uma vez, ainda que vrias tarefas dependam dela no mesmo ciclo de execuo.

Manual introdutrio do Apache ANT

 possvel tambm que uma tarefa venha a ser executada ou no dependendo do valor de uma propriedade (property). Isto definido atravs dos atributos if e unless. Como ainda no tratamos do assunto property ento vamos deixar para depois a exemplificao de como utilizar estes dois atributos de target.

Atributo name depends

Descrio Define o nome da tarefa. Define as tarefas dependentes. Se existirem vrias dependncias ento a lista deve ser separada por vrgulas (,). if Define o nome da propriedade que deve estar com valor para que a tarefa seja executada. unless Define o nome da propriedade que no deve estar com valor para que a tarefa seja executada. description Descrio breve do objetivo da tarefa.

Obrigatrio Sim No No No No

ATENO: comum que se utilize um hfem (-) antes do nome de uma tarefa para identificar aquelas tarefas que no devem ser chamadas diretamente. Ou seja, so tarefas utilizadas na lista de dependncias de outras tarefas (estas ltimas que so chamadas diretamente). Isto apenas uma regra e no algo obrigatrio. Exemplos:
<target name=inicializacao description=Prepara o ambiente para a construcao da aplicacao> ... </target> <target name=compilacao depends=inicializacao> ... </target> <target name=-limpeza description=Limpa os diretorios de deploy.> ... </target> <target name=deploy depends=-limpeza description=Realiza o deploy da aplicacao> ... </target>

Manual introdutrio do Apache ANT

10

3.2.3- Tasks
As tasks so as operaes que so realizadas dentro de cada tarefa. Estas operaes so na verdade programas que so executados para realizar cada uma das etapas que constituem uma tarefa. Existem muitas operaes aceitas pelo ANT e cada uma delas tem a sua lista de atributos. O formato de um elemento task :

<name attribute1="value1" attribute2="value2" ... />

Onde: name o nome do programa que ser executado, attributen o nome do parmetro que esperado e valuen o valor desse parmetro. possvel criar um identificador para uma operao. Desta forma a operao poder ser referenciada atravs deste identificador. Veja os exemplos abaixo.

<taskname id=taskID ... /> <script> taskID.setDir=/src/bin; </script>

Neste ltimo caso a operao taskID ter o seu atributo dir modificado para conter o valor /src/bin. Para conhecer a lista de operaes (tasks) existentes (apenas as principais) veja mais adiante no manual o captulo chamado ANT Tasks. Alm disso na ltima parte do manual mostraremos como criar uma nova operao (task) para o ANT atravs de um programa em JAVA.

3.2.4- Properties
Um projeto pode possuir propriedades. Estas propriedades de um projeto funcionam como se fossem variveis em uma linguagem de programao. A nica diferena que depois que a property recebe um valor este valor no pode ser modificado. O elemento property uma das possveis operaes (tasks) do ANT e logo possui a mesma regra de formao descrita no tem anterior. Ou seja:
<property name=fontes value=/src />

Depois de criada uma propriedade a mesma pode ser referenciada na forma ${nome da Manual introdutrio do Apache ANT 11

propriedade}.

Vamos a um exemplo:

<property name=fontes value=/src /> <property name=executaveis value=${fontes}/bin />

Alm da possibilidade de serem criadas as propriedades que forem necessrias o usurio poder usufruir das propriedades pr-existentes do ANT. Tambm possvel utilizar todas as propriedades que so acessveis atravs da classe System do JAVA (System.getProperties). Exemplos: Propriedades do ANT
basedir: diretrio base do projeto. Configurado atravs do atributo basedir do elemento <project>. ant.file: diretrio onde se encontra o arquivo de build. ant.version: verso do ANT. ant.project.name: nome do projeto que est sendo executado. ant.java.version: verso da JVM detectada pelo ANT.

Propriedades do System (veja todas as possibilidades no javadoc de System.getProperties)

os.name: nome do sistema operacional user.name: nome do usurio

Manual introdutrio do Apache ANT

12

3.2.5- Exemplo de um build completo

<?xml version="1.0"?> <project default="dist" name="Projeto Manual1"> <description>Um projeto simples.</description> <property name="srcDir" location="src"/> <property name="buildDir" location="build"/> <property name="distDir" location="dist"/> <target name="init"> <tstamp/> <mkdir dir="${buildDir}"/> <mkdir dir="${distDir}"/> </target> <target name="compile" depends="init"> <javac srcdir="${srcDir}" destdir="${buildDir}"/> </target> <target name="dist" depends="compile"> <jar destfile="${distDir}/package-${DSTAMP}.jar" basedir="${buildDir}"> <manifest> <attribute name="Built-By" value="${user.name}"/> <attribute name="Main-Class" value="package.Main"/> </manifest> </jar> <jar destfile="${distDir}/package-src-${DSTAMP}.jar" basedir="${srcDir}"/> </target> <target name="clean"> <delete dir="${buildDir}"/> <delete dir="${distDir}"/> </target> </project>

Manual introdutrio do Apache ANT

13

4- Rodando o ANT
O ANT uma ferramenta que pode ser executada de diversas formas mas a que mais comumente utilizada a linha de comandos. Entretanto, atualmente, vrias IDEs j suportam a criao de arquivos de build do ANT desde seus ambientes de desenvolvimento. Vale ressaltar que isso apenas facilita a vida para o desenvolvedor pois o arquivo que ser usado para a construo da aplicao compatvel com qualquer forma de execuo.

4.1- A partir da linha de comandos

Para executar o ANT a partir da linha de comandos basta digitar ant. O resultado ser a criao da aplicao seguindo o descrito no arquivo de build padro chamado build.xml. Ao digitar ant a ferramenta buscar no diretrio atual a existncia deste arquivo. Caso no encontre ser mostrada uma mensagem de erro. Existem vrios parmetros que podem ser passados na linha de comando que afetam a forma como a ferramenta executada. Veja a seguir os principais parmetros que podem ser utilizados.
ant [opes] [target [target2 [target3] ...]] Opes: -help -projecthelp -version -diagnostics -quiet, -q -verbose, -v -debug -emacs -logfile <file> -l <file> -logger <classname> -listener <classname> -buildfile <file> -file <file> -f <file> -D<property>=<value> -propertyfile <name> -inputhandler <class> -find <file> mostra na tela estas opes que esto aqui listadas. mostra na tela as informaes sobre o projeto. mostra na tela a verso do ant. mostra na tela informaes que podem ajudar a identificar problemas. no mostra informaes na tela. mostra o mximo de informaes possveis na tela. mostra na tela as informaes para debug de problemas. gera informaes de log sem formatao. gera um arquivo de log com o nome especificado. '' informa a classe responsvel pelo log. informa a instncia da classe que servir de listener para o projeto. use como arquivo de build o nome do arquivo especificado. '' '' atribui a uma propriedade do arquivo de build o valor especificado. informa o nome de um arquivo de onde carregar os valores para as propriedades do arquivo de build. nome da classe que ser reponsvel por tratar a entrada de dados. procure por um arquivo de build em toda a rvore de diretrios a partir do ponto onde foi digitado o

Manual introdutrio do Apache ANT

14

comando.

Exemplos:
ant -version ant -quiet ant -Dsrcdir=/src

4.2- Integrado com IDEs

Apesar de ser amplamente utilizado atravs da linha de comandos, as principais IDEs j disponibilizam mecanismos de integrao com o ANT. Isto vem a comprovar o enorme sucesso desta ferramenta que efetivamente um padro no desenvolvimento em JAVA. A lista completa das ferramentas que j esto integradas com o ANT pode ser vista diretamente no seu site em http://ant.apache.org/external.html#IDE%20and%20Editor%20Integration . Vamos exemplificar esta integrao com 2 ferramentas: uma free que o Eclipse e outra paga, o Oracle Jdeveloper.

4.2.1- Eclipse
O Eclipse oferece um grande nvel de integrao com o ANT atravs do Eclipse ANT Editor. Este editor possui syntax highlight alm de autocompletar os elementos que compem a estrutura de um arquivo de build.

Ao incluir um arquivo build.xml ao seu projeto o Eclipse automticamente o identificar como sendo um arquivo do ANT (caso voc utilize outro nome ento dever rever a associao de arquivos do

Manual introdutrio do Apache ANT

15

Eclipse). Sendo assim ao clicar com o boto direito do mouse sobre o arquivo aparecer no menu de contexto a opo Run Ant.... Ao escolher esta opo surgir uma tela como a que est abaixo.

Nesta tela se pode escolher qual tarefa (target) ser executada. A tarefa default vem sempre selecionada pois como j vimos anteriormente se nenhuma outra for identificada ento esta ser executada. Ao concluir a escolha de tarefas a executar bastar pressionar o boto Run que a tela de console ser apresentada mostrando o resultado da execuo do ANT.

Manual introdutrio do Apache ANT

16

Se for necessrio rever a associao de arquivos ao Eclipse, devido a utilizao de outro nome para o build, que no seja o build.xml, ento escolha a opo Preferences do menu Window e a seguir expanda o grupo Workbench. Selecione File Associations e coloque os parmetros conforme a sua necessidade.

Manual introdutrio do Apache ANT

17

4.2.2- Oracle Jdeveloper

O JDeveloper seguindo a tendncia das demais IDEs tambm possibilita a integrao com o ANT, desde que seja uma verso igual ou superior a 1.5. A integrao acontece de forma transparente sempre que um arquivo de build adicionado ao projeto. possvel tambm criar o arquivo de build dentro do projeto mas no existe um editor que d suporte aos elementos do ANT. Logo a nica verificao quanto a estrutura XML do arquivo e no quanto a sintaxe dos elementos. Mesmo assim se poder utilizar o editor de XML j existente na IDE para facilitar a edio do arquivo de build. Para incluir um arquivo de build j existente ao seu projeto utilize a opo File, tem New. A seguir selecione em Categories / General a opo ANT. Na lista de opes a esquerda escolha Buildfile from Existing XML File. Surgir ento a tela de escolha de arquivos para que seja identificado o arquivo XML que se deseja incluir ao projeto.

Manual introdutrio do Apache ANT

18

Aps a escolha do arquivo de build o seu projeto dever ficar da seguinte forma:

Observe que o arquivo de build pode ter qualquer nome. Uma das possibilidades com a integrao que o arquivo de build poder ser criado diretamente na IDE. Isto feito seguindo-se os passos anteriores s que escolhendo a opo Empty Buildfile. Neste caso dever ser informado o diretrio e o nome do novo arquivo de build. Para executar um arquivo de build clique com o boto direito sobre o arquivo desejado e escolha a opo Build Default Target no menu de contexto. Se no quiser executar a tarefa default ento escolha a tarefa desejada atravs da opo Build Target no mesmo menu de contexto (todas as tarefas estaro ali listadas).

Manual introdutrio do Apache ANT

19

5- Ant Tasks
O ANT proporciona um grande nmero de operaes, so mais de 130 opes j disponveis. Para facilitar o entendimento e o objetivo de cada operao iremos agrup-las. Estes grupos sintetizam tudo aquilo que pode ser feito atravs da ferramenta. Enfim, o que podemos fazer com o ANT? Compilar

<javac> <csc> <javadoc> <style> <junitreport> <stylebook> <java> <ant> <sql> <exec> <jar> <zip> <tar> <ear> <copy> <delete> <mkdir> <unjar> <unzip> <ftp> 20

Gerar Documentao

Executar programas

Empacotar e comprimir

Expandir, copiar e instalar

Acesso remoto

Manual introdutrio do Apache ANT

<telnet> <mail> <ejb-c> <ejb-jar> <junit> <script> <sound>

Montar componentes

Testar unidades de cdigo

Executar roteiros e sons

Criar novas operaes (tasks) caracterstica que proporciona ao ANT uma capacidade ilimitada de se expandir.

<taskdef>

obs: a lista de operaes em cada tem acima apenas uma pequena amostra, pois existem muitas outras opes. Para ver a lista completa utilize a documentao oficial do ANT em http://apache.ant.org/docs/manual/anttaskslist.html . O detalhamento de como funciona cada uma destas operaes pode ser encontrado na documentao oficial do ANT. Destacarei algumas operaes e tcnicas de como utiliz-las de forma produtiva.

5.1- Compilao
<javac> - executa o compilador java. Vale ressaltar que somente sero compilados os fontes que no possuirem seus equivalentes .class ou aqueles que tenham data mais recente que os .class. Ao terminar a compilao mostrado o nmero de fontes que foram efetivamente compilados. Principais parmetros:

Atributo srcdir

Descrio Localizao dos fontes. Diretrio de onde sero compilados os arquivos fonte.

Obrigatrio Sim

Manual introdutrio do Apache ANT

21

Atributo destdir classpath debug

Descrio Destino dos arquivos compilados. Diretrio onde sero armazenados os arquivos .class. Classpath que dever ser utilizado. Semelhante ao parmetro -classpath do javac. Informa se o arquivo compilado deve conter instrues de debug.

Obrigatrio No No No

Com os parmetros acima se resolve grande parte das tarefas de compilao mais comuns. Seguem alguns exemplos: - compila os fontes do diretrio src gerando os - dem ao enterior s que incluindo

<javac srcdir=src destdir=bin />

arquivos .class no diretrio bin.

<javac srcdir=src destdir=bin debug=true />

nos arquivos compilados instrues de debug. Entretanto existem compilaes que so mais complicadas, isto , exigem cuidados especiais. Para estes casos outros parmetros auxiliam na tarefa de compilao. So eles:

Atributo includes

Descrio Lista separada por vrgulas com os fontes que devem ser includos na compilao. Quando no informada esta lista ento todos os fontes do diretrio sero compilados. Arquivo contendo a lista dos fontes que devem ser considerados para a compilao. Lista separada por vrgulas com os fontes que devem ser excludos do processo de compilao. Se no for informado no se exclui nenhum arquivo do processo de compilao. Arquivo contendo a lista dos fontes que devem ser excludos da compilao. Indica se a compilao deve ser executada por um JDK a parte. Contm o caminho completo para o executvel responsvel pela compilao no caso em que fork for verdadeiro (true). Se no for informado um valor ento ser utilizado o compilador da VM que est executando o ANT.

Obrigatrio No

includesfile excludes

No No

excludesfile fork executable

No No No

Manual introdutrio do Apache ANT

22

Atributo optimize compiler

Descrio Indica quando a compilao deve ser feita de forma otimizada. O padro no compilar de forma otimizada. Indica o compilador a ser utilizado. Isto significa que podem ser usados outros compiladores java que no sejam o da JDK que executa o ANT. Caso no seja informado um compiler ento ser utilizado o da VM que est executando o ANT (propriedade build.compiler do arquivo de configuraes do ANT).

Obrigatrio No No

Exemplos mais complexos:

<javac srcdir="${src}" destdir="${build}" includes="mypackage/p1/**,mypackage/p2/**" excludes="mypackage/p1/testpackage/**" classpath="xyz.jar" debug="on" />

Neste caso os fontes so obtidos em ${src} e o resultado colocado em ${build}. No classpath includo a biblioteca xyz.jar. Sero compilados todos os fontes que estiverem nos pacotes p1 e p2 com exceo para o sub-pacote testpackage dentro de p1. Tambm possvel utilizar alguns parmetros na forma de elementos desta operao. Isto ocorre porque na verdade com a operao javac se est definindo um grupo de arquivos (fileset). Logo todo os elementos usados em fileset podero ser usados junto com o javac. Ser visto mais adiante como so criados os conjuntos de arquivos (fileset). Ex.:
<javac srcdir="${src}" destdir="${build}" includes="mypackage/p1/**,mypackage/p2/**" excludes="mypackage/p1/testpackage/**"> <classpath> <pathelement path=xyz.jar /> </classpath> </javac>

5.2- Operaes com arquivos

muito comum que no processo de construo (build) de uma aplicao seja definida a estrutura de armazenamento desta aplicao. Ou seja, se define durante o processo de construo a estrutura que ir receber os objetos da aplicao. Isto feito atravs da manipulao de arquivos e diretrios. Uma das Manual introdutrio do Apache ANT 23

vantagens de se utilizar o ANT para esta tarefa o fato das operaes funcionarem, geralmente, em diversas plataformas. Sendo assim o que for definido no arquivo build com relao a manipulao de arquivos funcionar em ambientes UNIX bem como Windows ou qualquer outro que possua um JVM. Obs: os parmetros que sero vistos no refletem todas as possibilidades mas sim as que julguei mas importantes e teis neste momento. <mkdir> - usado para criar diretrios (ou subdiretrios). Possui um nico parmetro, dir, que identifica o nome do diretrio a ser criado. Caso o diretrio j exista nenhum erro ocorrer mas obviamente a operao no ser realizada.

Atributo dir Ex.:

Descrio Identifica o nome do diretrio que ser criado.

Obrigatrio Sim

<mkdir dir=${src}/bin/> - cria um diretrio bin abaixo do diretrio <mkdir dir=${src}/bin/lib/> - cria um diretrio lib abaixo de bin.

${src}.

<copy> - usado para copiar arquivos ou conjunto de arquivos (fileset). Os arquivos somente sero copiado se no diretrio destino eles no existirem ou forem verses mais recentes. possvel gravar por cima de arquivos j existentes atravs do parmetro overwrite.

Atributo file tofile

Descrio Nome do arquivo que ser copiado. Novo nome do arquivo no diretrio destino. Para renomear um arquivo possvel utilizar a operao move, como veremos mais adiante. Diretrio de destino do arquivo. Informa se o arquivo poder ser gravado no diretrio destino caso j exista outro mais recente.

Obrigatrio Sim No

todir overwrite

No No

Ex.:
<copy file=${src}/criabanco.java todir=${src}/oldsources/>

- copia o

arquivo criabanco.java para o diretrio oldsource abaixo de ${src}.

Manual introdutrio do Apache ANT

24

<copy

/>

- faz o mesmo que o exemplo anterior mas renomeia o arquivo para criabanco_old.java.

file=${src}/criabanco.java tofile=${src}/oldsources/criabanco_old.java todir=${src}/oldsources overwrite=true

<delete> - usado para apagar um arquivo ou conjunto de arquivos (fileset) e at mesmo um diretrio com toda a sua estrutura (subdiretrios e arquivos).

Atributo file dir

Descrio Identifica o arquio a ser apagado. Identifica o diretrio a ser apagado.

Obrigatrio Sim (um dos dois parmetros deve existir) Sim (um dos dois parmetros deve existir)

Ex.:
<delete file=${lib}/mylib.jar/>

- apaga o arquivo mylib.jar que est no diretrio

lib.
<delete dir=${temp}/>

- apaga o diretrio temp e todos os seus subdiretrios e

arquivos. <move> - usado para mover um arquivo para um diretrio. Tambm possvel utilizar esta operao para renomear um arquivo. Ao contrrio da operao de cpia (copy) o move grava por cima (overwrite) sempre. Para que isso no ocorra necessrio desligar o atributo overwrite.

Atributo file tofile todir overwrite

Descrio Nome do arquivo que ser movido. Nome do arquivo no diretrio destino. Diretrio destino. Indica se o arquivo movido pode ser gravado por cima de outro com o mesmo nome. O valor padro true.

Obrigatrio Sim No No No

Ex.:
<move file=${bin}/mylib.jar todir=${lib}/>

- move o arquivo mylib.jar do - renomeia o

diretrio ${bin} para o diretrio ${lib}.

<move file=${bin}/mylib.jar tofile=${bin}/applib.jar/>

arquivo mylib.jar para applib.jar dentro do mesmo diretrio ${bin}.

Manual introdutrio do Apache ANT

25

<replace> - usado para substituir uma string dentro de um arquivo texto por outra informada como atributo. possvel que esta mudana ocorra no apenas em um arquivo mas em vrios (neste caso necessrio usar um conjunto de arquivos fileset).

Atributo file dir token value summary

Descrio Nome do arquivo onde ocorrer a substituio da string. Diretrio base utilizado no caso de a substituio ocorrer em vrios arquivos. String que dever ser substituda. String que substituir a informada em token. Caso no seja informada a nova string ento o valor default ser utilizado. Informa um resumo da operao aps a sua concluso. Informaes como: nmero de substituies, nmero de arquivos processados, etc.

Obrigatrio Sim No Sim No No

Ex.:
<replace file=readme.txt token=[ERR_NUM] value=1085/>

- substitui no

arquivo readme.txt a string [ERR_NUM] por 1085.

<replace summary=true/> - faz file=readme.txt token=[ERR_NUM] value=1085

o mesmo que o tem anterior mas mostra o resultado da operao. Neste caso mostrar o nmero de substituies efetuadas.

5.3- Empacotamento e compresso

Durante o processo de construo (build) de uma aplicao possvel que sejam criados alguns pacotes que facilitam a distribuio da aplicao. Como o ANT pode ser utilizado para outras tarefas alm da construo de aplicaes tambm possvel gerar arquivos compactados que venham a faciliatar a distribuio e/ou documentao de arquivos relacionados. Veremos a seguir duas operaes destinadas a estes fins. <jar> - usado para gerar um arquivo JAR. O destino do arquivo (destfile) deve ser informado e possvel refinar os arquivos que faro parte do JAR. A estrutura deste elemento define um conjunto de arquivos (fileset), logo possvel utilizar atributos como <include>, <exclude>, etc. O arquivo JAR, alm de juntar vrios arquivos gerando um novo arquivo com extenso JAR, guarda outras informaes que so identificadas atravs do metainf e do manifest. Sendo assim posssvel utilizar os elementos <metainf> e <manifest> para incluir no JAR as informaes necessrias.

Manual introdutrio do Apache ANT

26

Atributo destfile basedir compress includes includesfile excludes excludesfile manifest

Descrio Indica o caminho de destino do arquivo JAR. Indica o caminho onde esto os arquivos que sero includos no JAR. Indica se os arquivos devero ser compactados. O valor default True. uma lista separada por vrgula dos arquivos que devem ser includos no JAR. o nome de um arquivo contendo a lista de arquivos que devem ser includos no JAR. uma lista separada por vrgula dos arquivos que no devem ser includos no JAR. o nome de um arquivo contendo a lista de arquivos que no devem ser includos no JAR. Indica o nome do arquivo manifest que dever ser includo no JAR. Pode ser um arquivo ou at mesmo o nome de um outro JAR, neste caso o manifest dever estar localizado em METAINF/MANIFEST.MF

Obrigatrio Sim No No No No No No No

Ex.:
<jar destfile=${build}/jars/Exmp.jar basedir=${fontes}/classes/> - cria o arquivo Exmp.jar no diretrio ${build}/jars contendo todos os arquivos que esto em ${fontes}/classes. <jar destfile=${build}/jars/Exmp.jar basedir=${fontes}/classes excludes=${fontes}/classes/**.old /> - faz o mesmo que o descrito no exemplo anterior

mas sem incluir os arquivos *.old que

esto no diretrio ${fontes}/classes. Elementos opcionais: <metainf> - neste elemento possvel incluir um conjunto de arquivos (fileset) que sero includos ao META-INF do arquivo JAR. Se existir um manifest neste conjunto de arquivos ento o mesmo ser ignorado e uma mensagem de warning ser mostrada. <manifest> - com este elemento possvel definir o arquivo manifest no momento de criao do JAR em lugar de utilizar um arquivo externo. Caso seja definido um arquivo externo atravs do atributo manifest ento o manifest resultante ser o merge dos dois arquivos (o informado mais o definido atravs deste elemento).

Manual introdutrio do Apache ANT

27

Ex.:
<jar destfile="exmp.jar" basedir="."> <include name="build"/> <manifest> <attribute name="Built-By" value="${user.name}"/> <section name="common/class1.class"> <attribute name="Sealed" value="false"/> </section> </manifest> </jar> - cria o exmp.jar no diretrio raz e define o contedo do arquivo manifest.

<zip> - usado para criar um arquivo ZIP. A estrutura deste elemento define um conjunto de arquivos (fileset) e com isso possvel utilizar qualquer um dos sub-elementos de um fileset.

Atributo destfile basedir compress includes includesfile excludes excludesfile update

Descrio Indica o caminho de destino do arquivo ZIP. Indica o caminho onde esto os arquivos que sero includos no ZIP. Indica se os arquivos devero ser compactados. O valor default True. uma lista separada por vrgula dos arquivos que devem ser includos no ZIP. o nome de um arquivo contendo a lista de arquivos que devem ser includos no ZIP. uma lista separada por vrgula dos arquivos que no devem ser includos no ZIP. o nome de um arquivo contendo a lista de arquivos que no devem ser includos no ZIP. Informa se o arquivo ZI P que ser gerado dever substituir outro j existente com o mesmo nome (overwrite) ou se dever modific-lo (update - true). Se no for indicado este atributo o arquivo ZIP sempre substitui um j existente. Indica o que fazer no caso de existir um arquivo duplicado. Os valores possveis so: add, preserve e fail. O valor default add.

Obrigatrio Sim No No No No No No No

duplicate Ex.:

No

com todos os arquivos de ${build}/ manual. Se j existir um arquivo manual.zip ento o arquivo ser acrescentado dos arquivos que esto em ${build}/manual. Manual introdutrio do Apache ANT 28

<zip destfile="${dist}/manual.zip" basedir="${build}/manual" update="true" / > - gera um arquivo manual.zip em ${dist}

<zip destfile="${dist}/manual.zip" basedir="${build}/manual" excludes="index.html" /> - faz o mesmo que o exemplo anterior mas

exclui o arquivo index.html do

arquivo ZIP que ser gerado.

5.4- Gerando documentao

Os desenvolvedores JAVA j possuem a possibilidade de documentar enquanto escrevem os programas. A documentao feita atravs de tags que identificam para o programa JAVADOC o que deve conter o arquivo de documentao. A estrutura da documentao segue o padro definido pela SUN o que facilita muito a sua utilizao por parte dos desenvolvedores. Sendo assim, necessrio que os arquivos sejam processados atravs do programa JAVADOC para que sejam ento produzidos os arquivos HTML contendo a documentao de cada arquivo fonte. Como esta uma tarefa repetitiva podemos utilizar o ANT para automatiz-la (como veremos a seguir). Existem outras operaes para gerar documentao mas seguramente a mais utilizada a javadoc. <javadoc> - usada para gerar os arquivos de documentao a partir de fontes JAVA. Em outras palavras, executa o JAVADOC sobre um conjunto de arquivos fonte, gerando os arquivos HTML com a documentao.

Atributo sourcepath sourcefiles destdir Public Protected Private verbose

Descrio Indica onde devem ser encontrados os arquivos fontes. uma lista separada por vrgulas com os arquivos fontes que devem ser considerados. Diretrio de destino dos arquivos de documentao. Mostra apenas classes e membros pblicos. Mostra classes e mtodos pblicos/protected. Este o valor default. Mostra classes e membros pblicos/protected e privados.

Obrigatrio Sim(*) Sim(*) No No No No No

Mostra na tela mensagens informando o que est sendo feito durante o processamento de Javadoc. (*) pelo menos um destes atributos deve ser informado. Ex.:
<javadoc sourcepath="src" destdir="docs/api" verbose="true"

Manual introdutrio do Apache ANT

29

- gera os arquivos de documentao em docs/api de todos os fontes que esto em src. Durante a execuo do JAVADOC sero mostradas mensagens informando o que est sendo feito no processamento.
/>

5.5- Acesso remoto

No processo de construo(build) de uma aplicao podemos acessar remotamente alguns arquivos ou at mesmo copiar arquivos para localizaes remotas. Tambm possvel avisar (e at mesmo anexar arquivos), atravs de email, a realizao de uma tarefa. O acesso remoto til no processo de construo de aplicaes que atualmente se encontram em ambientes cada vez mais distribudos. <ftp> - usado para realizar aes de FTP. Esta operao implementa um cliente de FTP simples que permite enviar, receber e apagar arquivos que estejam armazenados remotamente. Esta operao utiliza comandos no formato UNIX.

Atributo server port userid password remotedir action binary separator Ex.:

Descrio Endereo do servidor de FTP. Nmero da porta do servidor FTP. O valor default 21. Nome do usurio para o servidor de FTP. Tsenha do usurio para o servidor de FTP. Nome do diretrio para onde sero copiados os arquivos. o diretrio no servidor de FTP. Ao FTP. So suportadas as seguintes aes: "send", "put", "get", "del", "list", "chmod" and "mkdir". O valor default send. Identifica se o modo binrio (yes) ou texto (no). O valor default yes. Identifica o separador de nomes. O valor default /.

Obrigatrio Sim No Sim Sim No No No No

<ftp server="ftp.apache.org" userid="anonymous" password="me@myorg.com"> <fileset dir="htdocs/manual"/> </ftp> - copia os arquivos do diretrio

htdocs/manual para o diretrio default do

usurio anonymous.
<ftp action="get" server="ftp.apache.org" userid="anonymous" password="me@myorg.com"> <fileset dir="htdocs/manual"> <include name="**/*.html"/> </fileset>

Manual introdutrio do Apache ANT

30

</ftp>

- faz download de todos os arquivos .html para o diretrio htdocs/manual.

<ftp action="del" server="ftp.apache.org" userid="anonymous" password="me@myorg.com"> <fileset> <include name="**/*.tmp"/> </fileset> </ftp> - exclui os arquivos .tmp do diretrio

default para o usurio anonymous.

<mail> - usado para enviar mensagens (email) SMTP. possvel enviar mensagens em formato texto ou usando arquivos com seu formato MIME identificado.

Atributo from tolist cclist bcclist message messagefile messagemimetype files mailhost mailport

Descrio Endereo de email de quem est enviando. Lista separada por vrgulas com os emails dos destinatrios. Lista separada por vrgulas com os emails das pessoas que sero copiadas. Lista separada por vrgulas com os emails das pessoas que sero copiadas. Mensagem a ser enviada. Escrito em formato texto. Arquivo contendo a mensagem que ser enviada. Tipo mime da mensagem. O valor default text/plain. Lista separada por vrgulas com o nome dos arquivos que sero anexados. Hostname do servidor SMTP. O valor default localhost. Porta TCP do servidor SMTP. Valor default 25.

Obrigatrio Sim Sim(*) Sim(*) Sim(*) Sim(**) Sim(**) No No

No No

subject Assunto da mensagem. (*) pelo menos um destes atributos deve ser informado. (**) pelo menos um destes atributos deve ser informado.

possvel que alguns destes atributos sejam definidos atravs de sub-elementos. So eles: <from> / <to> / <cc> / <bcc> - estes elementos tem o mesmo sentido que os atributos from, tolist, cclist e bcclist respectivamente.

Manual introdutrio do Apache ANT

31

Atributo name address <message> Atributo src mimetype Endereo de email.

Descrio Nome com que ser mostrado (display).

Descrio Nome do arquivo que contm a mensagem. Tipo mime do arquivo contendo a mensagem.

Se no for informado o atributo src ento possvel escrever a mensagem diretamente no corpo do elemento message. Ex.:
<mail mailhost="smtp.red.com" mailport="1025" subject="Aplicao comercial" subject="Nova verso do sistema comercial."> <from address="ast@home.com"/> <to address="all@xyz.com"/> <message> A nova verso da aplicao comercial j est disponvel. </message> </mail> - envia uma mensagem para ast@home.com sobre a nova verso do sistema

comercial.

Manual introdutrio do Apache ANT

32

6- Conceitos e Tipos
O ANT trabalha de forma transparente para o usurio novato. Entretanto importante conhecermos alguns detalhes que possibilitam um maior controle sobre as operaes individuais e sobre como o ANT interpreta certos conceitos. Nesta parte vamos entender os conceitos que permeiam o funcionamento da ferramenta e como podemos criar tipos que facilitaro a definio do que deve ser feito nas operaes que suportem este tipos.

6.1- Conceitos
Os conceitos so as premissas pelas quais a ferramenta orienta o seu funcionamento genrico. build.sysclasspath: o valor desta propriedade indica como o classpath ser interpretado durante a execuo do ANT. Os possveis valores para esta propriedade so:

only: com este valor ser utilizado o classpath definido no sistema. Nenhum outro classpath definido atravs de atributos ser considerado. ignore: com este valor o resultado exatamente oposto ao obtido com only. Ou seja, se usa somente o classpath definido nos atributos e se ignora o classpath do sistema. last: com este valor o classpath concatenado a qualquer outro que tenha sido definido por atributos. A concatenao feita no final do ltimo classpath. first: com este atributo qualquer classpath definido atravs de atributos ser concatenado ao classpath do sistema.

Atributos comuns a todas as operaes: todas as operaes tm os atributos abaixo em comum. Isto significa que em qualquer operao se pode utilizar os atributos da tabela abaixo.

Atributo id

taskname

description

Descrio Obrigatrio Identificador nico da operao. Este ID pode No ser usado para referenciar a operao dentro dos scripts. Nome diferente para a operao dentro desta No instncia da operao. Este nome aparecer no log. Espao para colocar comentrios. No

Manual introdutrio do Apache ANT

33

6.2- Tipos
Os tipos so utilizados para definir conjuntos de informaes que sero manipuladas de forma unitria. Sendo assim so mais comuns os tipos para manipulao de diretrios e arquivos pois, depois de definidos estes tipos, possvel manipular um conjunto de arquivos atravs de um nico nome. Entretanto existem outros tipos que auxiliam na identificao do conjunto de informaes sobre o qual se deseja aplicar determinadas operaes. Os tipos detalhados a seguir no so todos os existentes mas so aqueles mais utilizados. Para conhecer a lista completa utilize o manual do ANT em http://ant.apache.org/manual .

6.2.1- Descrio (description)

Este tipo permite definir uma descrio para o projeto. Esta descrio aparecer quando for utilizada a opo -projecthelp na linha de comando do ant (ant -projecthelp). Este tipo no possui atributos.

<description> Descrio do projeto. </description>

6.2.2- Operaes com estruturas de diretrios

As operaes com estruturas de diretrios so amplamente utilizadas nas demais operaes que vimos anteriormente. Existem vrias operaes que possuem estruturas de diretrio internamente como por exemplo <javac>, <zip>, etc. Estas operaes utilizam de forma ampla os padres (patterns) e por isso fundamental que se tenha esse conhecimento bem fundamentado. Padres (patterns) Padres so usados para incluso e excluso de condies de mapeamento de nomes de diretrios. Os padres bsicos se assemelham muito com os utilizados em comandos DOS ou UNIX, so eles: * - para mapeamento de um ou mais caracteres. Ex.: *.java significa que qualquer nome de arquivo permitido que tenha extenso .java ser includo ou excludo da condio ao qual est associada. ? - para mapeamento de apenas um caracter. Ex.: myap?.java significa que qualquer nome de arquivo que comece com myap e tenha apenas mais uma letra no nome alm de extenso .java ser Manual introdutrio do Apache ANT 34

includo ou excludo da condio ao qual est associada. Vale lembrar que se pode associar * e ? sem nenhum tipo de limitao. Ex.: / lib/*/app/*.java , /lib/*/app_?/*.html . Como possvel utilizar * para mapear diretrios e como isso se tornou muito comum para mapear uma estrutura totalmente varivel , foi criado o **. Este ltimo identifica que qualquer nvel de estrutura de diretrios poder ser mapeada. Ex.: /lib/**/*.java isto significa que qualquer estrutura de diretrios abaixo de /lib ser considerada vlida para encontrar arquivos com extenso .java. Isto facilita muito a escrita pois no necessrio especificar todas as condies de subnveis que se deseja considerar (alm de tornar a instruo totalmente reutilizvel pois independer da estrutura que for criada). Se um padro for definido com terminador / ou \ o ANT automatocamente considerar a presena de um ** aps o terminador. Ex.: /test/ ser interpretado como /test/**. A utilizao de padres (patterns) nas operaes com diretrios possibilita a incluso e excluso de subconjuntos de arquivos/diretrios. Sendo assim possvel definir um subconjunto com o qual se deseja trabalhar. Existem duas formas de se definir um subconjunto: 1- Atravs da incluso de arquivos/diretrios que correspondo a um padro. 2- Atravs da excluso de arquivos/diretrios que correspondo a um padro. Ao utilizar ambas condies temos um importante ferramental de definio exata do subconjunto de arquivos/diretrios que se quer utilizar. Ex.:
<copy todir="${dist}"> <fileset dir="${src}" includes="**/images/*" excludes="**/*.gif" /> </copy> - sero copiados todos os arquivos

abaixo de images, respeitando qualquer nvel de diretrios desde ${src}, com exceo dos arquivos com extenso .gif. Existem algumas definies que so excludas de qualquer operao de diretrios, so elas:
**/*~ **/#*# **/.#* **/%*% **/._*

Manual introdutrio do Apache ANT

35

**/CVS **/CVS/** **/.cvsignore **/SCCS **/SCCS/** **/vssver.scc **/.svn **/.svn/**

Para

que

no

sejam

utilizadas

estas

excluses

necessrio

utilizar

atributo

defaultexcludes="no".

6.2.3- PatternSet
Os padres (patterns) podem ser organizados em conjuntos (sets) e identificados (atravs do atributo id) para posterior utilizao. A vantagem de ser definido um patternset que sua reutilizao pode ser feita em todo o projeto. Entretanto possvel definir um patternset vlido somente para uma operao. Se o objetivo for a reutilizao ento o patternset deve ser definido no mesmo nvel que uma tarefa (target).

Atributo includes

Descrio Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que devem ser inludos. Se no for especificado um padro para nome de arquivos ento ser utilizado * como default. includesfile Nome de um arquivo contendo os padres para incluso. Cada linha do arquivo dever conter um padro. excludes Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que sero excludos. Se no for especificado ento nenhum arquivo ser excludo(exceo feita apenas para os padres de excluses default). excludesfile Nome de um arquivo contendo os padres para excluso. Cada linha do arquivo dever conter um padro. Ex.:
<patternset id="sources" includes="src/**/*.java" excludes="**/*Test*" /> - cria um patternset incluindo todos

os arquivos com extenso .java que estiverem abaixo de src e exclui tudo que estiver abaixo de diretrios que possuam Test em alguma parte do nome. possvel criar patternset atravs de subelementos no lugar de atributos. Os subelementos permitidos so:

Manual introdutrio do Apache ANT

36

<include> / <exclude> Atributo name if unless Descrio Nome do padro a ser includo/excludo. Usa o padro somente se a propriedade estiver com valor. Usa o padro somente se a propriedade no estiver com valor. Obrigatrio Sim No No

<includesfile> / <excludesfile> Os parmetros so os mesmos de <include> / <exclude>. Ex.:

<patternset id="sources"> <include name="src/**/*.java"/> <include name="**/*.html" if="documentar"/> <exclude name="**/*Test*"/> </patternset> - Faz o mesmo que o exemplo anterior mas

inclui os arquivos com

extenso .html se a propriedade documentar tiver com valor.

6.2.4- FileSet
Os conjuntos de arquivos (filesets), como o prprio nome diz, se trata de um agrupador de arquivos. Este conjunto definido atravs de padres (patterns) e pode ser usado internamente a operaes que se comportem como agrupadoras de arquivos ou no mesmo nvel de tarefas (target, onde poder ser mais reutilizvel).

Atributo Descrio dir Indica o diretrio raz que contn os arquivos deste fileset. defaultexcludes Indica quando as excluses default (visto anteriormente na parte de padres) devem ser utilizadas. Se for omitido este parmetro ento ser utilizado o conjunto padro de excluses. includes Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que devem ser inludos. Se no for especificado um padro para nome de arquivos ento ser utilizado * como default. includesfile Nome de um arquivo contendo os padres para incluso. Cada linha do arquivo dever conter um padro. excludes Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que sero excludos. Se no for especificado ento nenhum arquivo ser excludo(exceo feita apenas para os padres de excluses default).

Obrigatrio Sim No

No

No No

Manual introdutrio do Apache ANT

37

Atributo excludesfile

Descrio Nome de um arquivo contendo os padres para excluso. Cada linha do arquivo dever conter um padro.

Obrigatrio No

Como o fileset definido atravs de patternsets ento permitido que se usem os subelementos de patternsets. Sendo assim so vlidos os subelementos: <include> / <exclude> / <includesfile> / <excludesfile>. Ex.:
<fileset dir="${server.src}"> <include name="**/*.java"/> <exclude name="**/*Test*"/> </fileset> - define um fileset a partir

do diretrio ${server.src} incluindo todos os arquivos com extenso .java e exclundo todos os arquivos em diretrios contedo no nome Test.

6.2.5- DirSet
Os conjuntos de diretrios (dirsets), como o prprio nome diz, se trata de um agrupador de diretrios. Este conjunto definido atravs de padres (patterns) e pode ser usado internamente a operaes que se comportem como agrupadoras de arquivos/diretrios ou no mesmo nvel de tarefas (target, onde poder ser mais reutilizvel).

Atributo dir includes

includesfile excludes

excludesfile

Descrio Indica o diretrio raz que contn a estrutura deste dirset. Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que devem ser inludos. Se no for especificado um padro para nome de arquivos ento ser utilizado * como default. Nome de um arquivo contendo os padres para incluso. Cada linha do arquivo dever conter um padro. Lista separada por vrgulas ou espaos dos padres (patterns) de arquivos e diretrios que sero excludos. Se no for especificado ento nenhum arquivo ser excludo(exceo feita apenas para os padres de excluses default). Nome de um arquivo contendo os padres para excluso. Cada linha do arquivo dever conter um padro.

Obrigatrio Sim No

No No

No

Como o dirset definido atravs de patternsets ento permitido que se usem os subelementos de

Manual introdutrio do Apache ANT

38

patternsets. Sendo assim so vlidos os subelementos: <include> / <exclude> / <includesfile> / <excludesfile>. Ex.:
<dirset dir="${build.dir}"> <include name="apps/**/classes"/> <exclude name="apps/**/*Test*"/> </dirset> - define um dirset agrupando todas

as classes existentes no diretrio classes (lembre-se que podem existir outros arquivos que no sejam classes) mas exclu aquelas que estiverem em deiretrios que contenham no nome a palavra Test.

6.2.6- FilterSet
Os conjuntos de filtros (filtersets), como o prprio nome diz, se trata de um agrupador de filtros. Os filtros so definidos como pares de elementos a serem buscados e substitudos. Estes elementos podem ser definidos atravs de atributos ou arquivo externo. O filterset pode ser usado internamente a operaes que suportem filtros ou definidos no mesmo nvel de tarefas (target, onde poder ser mais reutilizvel). Os filtersets permitem o uso dos atributos id e refid. Com estes atributos possvel definir um identificador para um filtro e reutiliz-lo atravs do atributo refid.

Atributo Dscrio begintoken String que identifica o incio do elemento que ser comparado (token). Ex.: @data@ endtoken String que identifica o fim do elemento que ser comparado (token). Ex.: @data@

Default Obrigatrio @ No @ No

Como definimos antes os filtersets trabalham agrupando filtros. Logo necessitamos ver como definir estes filtros. <filter> Atributo Descrio token value O elemento a ser buscado e substitudo. O valor a substituir o elemento buscado. Obrigatrio Sim Sim

Manual introdutrio do Apache ANT

39

<filtersfile> Atributo Descrio file Arquivo de propriedades contendo os pares elemento a ser buscado/substitudo e valor a substituir. Ex.:
<filterset id="filtrodata" begintoken="%" endtoken="*"> <filter token="DATE" value="${TODAY}"/> </filterset> <copy file="${build.dir}/version.txt" toFile="${dist.dir}/ version.txt"> <filterset refid="filtrodata"/> </copy>

Obrigatrio Sim

Neste exemplo se define um filtro que substitui a string DATA pela data atual. Este filtro reutilizado na operao de cpia do arquivo version.txt para substituir o valor de DATE pela data atual.

6.2.7- Selectors
Os selectors so mecanismos de seleo que permitem que um fileset seja identificado por outras opes que no apenas <include> / <exclude>. Os selectors so utilizados dentro das definies de filesets. Existem vrios tipos de selector mas vamos nos ater aos mais utilizados. <contains> - usado para selecionar arquivos que possuam uma determinada string. Atributo text casesensitive Descrio Identifica o texto que ser buscado. Indica se devem ser observados os caracteres em maisculas e minsculas. O valor default true. Obrigatrio Sim No

Ex.:
<fileset dir="${doc.path}" includes="**/*.html"> <contains text="script" casesensitive="no"/> </fileset> - define um fileset incluindo arquivos com extenso

.html que possuam

a palavra script no corpo do arquivo.

Manual introdutrio do Apache ANT

40

<date> - usado para selecionar arquivos que tenham sido alterados antes ou depois de uma data especfica.

Atributo datetime when

Descrio Indica a data que ser usada na validao. O formato segue a string MM/DD/YYYY HH:MM AM_or_PM. Indica a situao de comparao com a data indicada no primeiro atributo. As possibilidades so:

Obrigatrio Sim No

before seleciona os arquivos com data de modificao exatamente anterior ao atributo datetime. after - seleciona os arquivos com data de modificao exatamente posterior ao atributo datetime. equal seleciona os arquivos com data igual ao definido em datetime

O valor default equal. Ex.:

<fileset dir="${jar.path}" includes="**/*.jar"> <date datetime="01/01/2001 12:00 AM" when="before"/> </fileset> - define um fileset incluindo os arquivos com extenso .jar

com data de

modificao anterior a 01/01/2001 12:00 AM.

<depend> - seleciona arquivos que tenham sido modificados mais recentemente que outras verses do mesmo arquivo em outros diretrios.

Atributo targetdir

Descrio Indica o diretrio onde esto os arquivos que sero comparados.

Obrigatrio Sim

Ex.:

<fileset dir="${ant.1.5}/src/main" includes="**/*.java"> <depend targetdir="${ant.1.4.1}/src/main"/> </fileset> - define um fileset contendo apenas os arquivos com extenso

.java

mais recentes que as existentes no diretrio ${ant.1.4.1}/src/main.

Manual introdutrio do Apache ANT

41

<size> - seleciona arquivos que sejam maiores ou menores que um determinado tamanho.

Atributo value units

when

Descrio Obrigatrio Indica o tamanho que ser usado para o teste. Sim Indica a unidade de medida em que foi informado o atributo No value. Valores possveis: "k","M", ou "G". O default no usar este atributo o que faz com que o valor de value seja intepretado em bytes. Indica como deve ser interpretada a comparao com o No tamanho informado no atributo value. Valore possveis:

less seleciona arquivos com tamanha menor. more seleciona arquivos com tamanho maior, equal selecion arquivos de igual tamanho.

O valor default equal. Ex.:

<fileset dir="${jar.path}"> <patternset> <include name="**/*.jar"/> </patternset> <size value="4" units="Ki" when="more"/> </fileset> - define um fileset com todos os arquivos

de extenso .jar maiores de 4kb que esto a estrutura abaixo de ${jar.path}.

Manual introdutrio do Apache ANT

42

7- Como criar uma nova task

Como vimos at agora o ANT possui uma quantidade de operaes (tasks) que possibilitam a realizao de muitas atividades. Entretanto, pode existir alguma operao que no exista, mas que voc como desenvolvedor j tenha feito um programa JAVA para resolv-la. Se este o caso, ento voc pode extender as operaes do ANT incluindo esta operao como mais uma possibilidade. possvel que voc execute programas externos ao ANT atravs da operao exec mas, se o seu programa em JAVA, fica mais elegante voc extender as operaes do ANT (at porque faz-lo no algo complicado). Para criar uma operao simples basta derivar a sua classe de org.apache.tools.ant e sobreescrever o mtodo execute(). Ento o esqueleto de sua nova operao ser:
import org.apache.tools.ant.BuildException; import org.apache.tools.ant.Task; public class myTask extends Task { public void execute() throws BuildException {} }

Observe que o mtodo execute() dispara uma exceo BuildException. Isto significa que se algo der errado ento passaremos para o ANT a informao de erro que ele tratar de mostr-la ao usurio. As operaes normalmente se utilizam de atributos para parametrizar o seu funcionamento. Para fazer isso necessrio criar mtodos set com o nome do atributo desejado. Por exemplo:

public void setMeuAtributo(String str) { }

Note que o parmetro deste mtodo uma String pois como vimos os atributos so normalmente configurados atravs de strings. Vale lembrar que poderamos utilizar outros tipos mas no vamos nos deter neste ponto aqui. Como voc pode concluir se implementarmos uma classe como descrito acima, incluindo o mtodo
setMeuAtributo(),

o ANT passar a contar com uma nova operao chamada myTask que ter como

atributo MeuAtributo. A utilizao desta operao igual as demais, ou seja:

Manual introdutrio do Apache ANT

43

<myTask MeuAtributo=exemplo />

Desta forma podemos extender facilmente as operaes do ANT o que nos d a possibilidade de criar qualquer operao que seja necessria para as nossas atividades. Lembre-se, entretanto, que muitas vezes possvel utilizar as operaes j exsitentes para realizar as nossas tarefas (a lista de operaes grande). Se o seu caso pede a extenso do ANT ento vale a pena se aprofundar mais no assunto e o melhor lugar para encontrar as informaes no prprio manual do ANT em http://ant.apache.org/manual .

Manual introdutrio do Apache ANT

44

8- Prximos passos
Agora que voc j conhece a ferramenta ANT e com certeza pode perceber o seu portencial, importante que se aprofunde no assunto. O ANT pode ser utilizado para trazer produtividade a projetos e aplicaes. amplamente utilizado no s como ferramenta de build mas tambm como ferramenta de suporte a metodologias de desenvolvimento, como XP. Nesta linha se destaca o conceito de integrao contnua alm da automatizao de testes, integrado ao framework JUnit. Existe documentao disponvel na internet e nos grupos de usurios Java (JUGs) sobre estes assuntos. Uma pesquisa no Google poder ajudar a selecionar os assuntos que mais lhe agradem sobre o tema ANT.

Sobre o autor
Alexandro Strack formado em Matemtica com ps-graduao em anlise e gerncia de sistemas pela PUC-RJ. Atua na rea de desenvolvimento desde 1989. Desde o incio de sua carreira profissional trabalhou com Orientao a Objetos atravs de linguagens de 3a e 4a geraes. Possui a certificao SCJP 1.4 e trabalha com a tecnologia JAVA desde 2000. Atua neste momento em vrios projetos JAVA voltados para web alm de ser membro do projeto open source Hotwork ( http://hotwork.sourceforge.net ).

Bibliografia
Manual oficial do ANT http://ant.apache.org/manual Apache Ant 101: Make Java builds a snap http://www.ibm.com/developerWorks Java Magazine Ed. 2 Tutorial ANT (GUJ) - http://www.guj.com.br/user.article.get.chain?page=1&article.id=30 Construo de Aplicaes JAVA com ANT Helder da Rocha http://www.argonavis.com.br

Manual introdutrio do Apache ANT

45