emopluppen Användning av "Ant" Version: 1.4 ( 2002/04/26 07:27:52 UTC) Niklas Backlund
Sammanfattning Det här dokumentet handlar om programmet Ant, som är en byggmiljö för programutvecklingsprojekt. Dess roll är att automatisera tråkiga uppgifter, som att t ex generera dokumentation, kopiera filer till web-kataloger etc. Här tar jag bara upp hur man använder Ant, inte hur man konfigurerar det. Vill du veta mer är det bara att vända dig till http://jakarta.apache.org/ant (Ant's hemsida). Innehållsförteckning 1 - Vad är Ant?... 3 2 - Installation av Ant... 2.1 - På KTH... 2.2 - Hemma... 3 3 3 3 - Att använda Ant... 3.1 - Katalogstruktur... 3.2 - Targets... 3.3 - Properties... 3.4 - Tokens... 4 4 5 6 7 Referenser... 8
1 - Vad är Ant? Ant är ett program som man använder för att automatisera saker som behöver göras ofta medan man utvecklar. Det kan vara allt ifrån kompilering av programkod, kopiering av filer, automatisk testning av programmet, till generering av dokumentation. Förutom att man slipper sitta och upprepa alla dessa kommandon, ger Ant en annan stor fördel: Det håller reda på tidsstämplarna för varje fil, så att det alltid bara kopierar eller kompilerar om de filer som har ändrats sedan förra körningen. När projektet börjar växa i storlek, inser man snabbt hur mycket tid detta sparar. Ant är skrivet i Java, och fungerar därmed på de flesta plattformar. Det är dessutom gjort så att det är lätt att lägga till ny funktionalitet. Redan i dagsläget går det att göra en hel del olika saker med Ant. Du kan t o m säga åt Ant att hämta en viss hemsida eller lägga upp filer på en FTP-server. Du kan läsa mer om detta på http://jakarta.apache.org/ant (Ant's hemsida). 2 - Installation av Ant 2.1 - På KTH Först och främst måste du ha Java installerat. Om du inte redan har det, lägger du till jdk/latest till dina moduler, förslagsvis genom att lägga till den i filen ~/.modules. Jag har installerat Ant på projektarean, i katalogen /misc/projects/proj02/emoplupp/usr/ant så allt du behöver göra är att lägga till följande rad i filen ~/.environment: setenv PATH /misc/projects/proj02/emoplupp/usr/ant/bin:$path Nästa gång du loggar på ditt UNIX-konto kommer ant att finnas tillgängligt som kommando. För att fixa det utan att logga ut, kan du också köra filen manuellt: source ~/.environment Du kan testa att det fungerar genom att skriva ant -version 2.2 - Hemma För att installera Ant hemma (under t ex Windows), bör du först ladda hem senaste versionen av JDK från http://java.sun.com (Java's hemsida) och installera det. Sedan laddar du hem Ant från http://jakarta.apache.org/ant (Ant's hemsida) och installerar det också. Vi använder dessutom en del utökad funktionalitet i Ant för att kunna automatgenerera dokumentationen. Denna funktionalitet är beroende externa bibliotek för att kunna fungera. Dessa ligger fördelade i ett antal JAR-filer som måste finnas i Ant's sökväg. Detta görs -3-
enklast genom att lägga filerna i Ant's lib-katalog. Filerna är: xalan.jar xml-apis.jar xercesimpl.jar batik.jar avalon-framework-4.0.jar fop.jar logkit-1.0.jar xerces-1.2.3.jar fop-anttask.jar Dessa filer laddar du lättast hem från skolan via FTP. Du hittar dem under katalogen /misc/projects/proj02/emoplupp/usr/ant/lib De externa verktyg vi använder oss av kommer båda två från Apache: Det ena är en XSLT-processor som heter Xalan, och används för att transformera XML till andra format (HTML, XML, XSL-FO, SQL,...). Du kan läsa mer om den på http://xml.apache.org/xalan-j (Xalan's hemsida). Det andra heter Fop och används för att rendera ett XSL-FO-dokument till PDF. Den kan du läsa mer om på http://xml.apache.org/fop (Fop's hemsida). Obs! fop-anttask.jar har jag själv utvecklat för att underlätta generering av PDF-filer från Ant. Om du behöver göra några ändringar (eller bara är intresserad av hur det ser ut) är det bara att checka ut källkoden med kommandot cvs co fop-anttask. (För att bygga JAR-filen skriver du ant dist.) 3 - Att använda Ant 3.1 - Katalogstruktur Som jag redan gått igenom i CVS-dokumentationen, så har våra arbetskataloger den här strukturen: Eftersom körning av Ant ger upphov till en hel del dynamiskt genererade filer, främst dokumentation, är det inte särskilt snyggt om dessa hamnar i samma filträd som sina källor. -4-
Istället skapar Ant en tillfällig katalog att bygga i, build, som ligger rakt under arbetskatalogens rot: build checkas aldrig in i CVS-filupplaget, och för att försäkra oss om att detta inte sker av misstag, har jag sagt åt CVS-servern att ignorera denna katalog. Obs! Du borde se på build som en sk flyktig katalog. Du bör alltså aldrig manuellt ändra filer under detta träd; Ant ansvarar för innehållet, och skulle lika gärna kunna radera hela trädet nästa gång det körs. 3.2 - Targets För att Ant ska kunna vara användbart för så många olika uppgifter som möjligt, vill man kunna ange vad Ant ska göra varje gång man kör det. I specifikationsfilen build.xml delar vi in arbetsuppgifterna i något som kallas targets. Ett exempel på ett target kan t ex vara "build-html-docs", som läser igenom alla XML-filer i dokumentations-katalogen och genererar HTML-versioner av de dokument som har ändrats sedan förra gången kommandot kördes. För att köra ett target, skriver du helt enkelt ant target-namn För att se information om de targets som finns projektet, ställ dig i roten till din arbetskatalog (samma katalog som build.xml ligger i), och skriv ant -projecthelp När det här dokumentet skrevs, gav detta kommando följande utskrift på skärmen: Buildfile: build.xml Default target: deploy Builds and deploys wwwroot to the webserver. Main targets: all clean database deploy deploy-html-docs docs undeploy Builds wwwroot, docs and db scripts, then deploys wwwroot. Wipes out the build dir. Builds all database scripts and docs. Builds and deploys wwwroot to the webserver. Deploys all HTML docs to the project web dir. Generate all documentation as HTML and PDF. Erases the deploy dir -- Use with care! -5-
Subtargets: build-database-docs build-html-docs build-pdf-docs build-wwwroot init BUILD SUCCESSFUL Total time: 2 seconds "Default target" anger vilket target som utförs om du bara skriver ant. Ett target är ofta beroende av ett eller flera andra targets: T ex har jag gjort deploy beroende av build-wwwroot. Detta innebär att varje gång du kör deploy, så körs först build-wwwroot för att se till att den senaste versionen av wwwroot ligger i build-trädet innan filerna kopieras upp till web-servern. 3.3 - Properties Det finns vissa parametrar i projektet som man skulle behöva byta ut ibland, t ex vilken databasserver man vill generera script för, eller var man vill att dokumentationen ska hamna. I Ant kan man göra detta genom att definiera ett antal variabler, sk properties, i build.xml. Man refererar sedan till dessa properties på flera ställen i build.xml, så att man bara behöver ändra propertyn's värde på ett enda ställe. Vi har t ex propertyn database-url, som pekar ut adressen till databas-servern som Emopluppen ska prata med, t ex buddard.homelinux.com. Om du sitter och testar hemma, kanske du hellre kör mot en lokal databas-server istället. Då ändrar du bara propertyns värde till localhost. Eftersom vi alla sitter och jobbar mot samma build.xml (via CVS), vore det ju inte så bra om vi höll på och ändrade i den varje gång vi tillfälligt vill ändra värdet på en property. Vi borde bara ändra property-värden i build.xml om det är en mer permanent ändring, som alla i projektet har användning för. För tillfälliga och/eller presonliga tilldelningar av propertyvärden, finns det en mekanism i Ant som gör att du kan "kortsluta" property-värden med en fil i din arbetskatalog som heter build.properties. Det är en helt vanligt textfil där du tilldelar properties värden på formatet property-namn=värde med en propertytilldelning per rad. Denna fil ignoreras också av CVS, så den kan du inte checka in. I skrivande stund finns följande properties definierade i vårt projekt: build-dir Katalogen där Ant lägger det byggda filträdet. Default är emoplupp/build. deploydir Katalogen dit Ant kopierar www-roten när man vill testa Emopluppen. Default är katalogen public_html/emoplupp i din hemkatalog. project-docroot Dokumentationskatalogen på vår projekthemsida. Default satt till public_html/docs i projektarean. database-command Kommando för att starta databas-klienten. Default är mysql. -6-
database-url Databas-serverns hostname. Denna är bra att ändra till localhost när man testar hemma. database-user Det användarnamn som ska användas för att logga in på databasservern. Default är emoplupp. database-password Lösenordet för att logga in på databasen. Än så länge används inte den propertyn någonstans. 3.4 - Tokens En annan användbar funktion som finns i Ant är sk tokens. Ett token är ett nyckelord man kan skriva i sin källkod eller sina dokument. När Ant sedan kompilerar eller kopierar filen, så byts nyckelordet ut mot ett värde man har specifierat i build.xml. För att Ant ska förstå att det är ett nyckelord, skriver man det på formatet @nyckelord@, där nyckelordet dessutom måste finnas definierat i build.xml - Annars händer ingenting. De tokens som finns definierade i skrivande stund är: @database-command@ @database-url@ @database-user@ @database-password@ och de byts alla ut mot värdet på propertyn med samma namn. Detta kan man dra nytta av i ett script som ser ut så här: @database-command@ -h @database-url@ -u @database-user@ När scriptet sedan kopieras av Ant, byts nyckelorden ut mot värden, och resultatet kan t ex bli så här: mysql -h buddard.homelinux.com -u emoplupp Obs! I förlängningen kan vi också utnyttja detta i våra PHP-script. Bara ändra propertyn's värde i build.properties och kör om Ant, så ändras innehållet i scripten. -7-
Referenser Ant's hemsida http://jakarta.apache.org/ant Java's hemsida http://java.sun.com Xalan's hemsida http://xml.apache.org/xalan-j Fop's hemsida http://xml.apache.org/fop