AgilElephant ja CruiseControl Tekijä: Juha Kaarlas Omistaja: ElectricSeven Aihe: CruiseControl ja AgilElephant Sivu 1 of 9
Dokumentti Historia Muutoshistoria Revision Revision Yhteenveto muutoksista Revision tekijä Numero Päiväys 1.0 2005-03-09 Kaikki tärkeimmät asiat kuvattu Juha Kaarlas Hyväksyjät Tämä dokumentti vaatii seuraavien henkilöiden hyväksymiset Nimi Juha Kaarlas Tehtävä Projektipäällikkö Katselmoinnit Tämä dokumentti vaatii seuraavien henkilöiden katselmoinnin Nimi Tehtävä Ei katselmointia Jakelu Tämä dokumentti jaetaan seuraaville henkilöille Nimi Projektiryhmä Asiakas Tehtävä Mielenkiinnosta Pyynnöstä Aihe: CruiseControl ja AgilElephant Sivu 2 of 9
Sisällysluettelo 1. Esittely...4 1.1 Tarkoitus...4 2. Johdanto...5 3. Käyttöönotto...6 4. CruiseControl ja AgilElephant...7 4.1 Kääntäminen ja asennus...7 4.2 Tietokannan puhdistus ja alustus...7 4.2.1 Buildi on rikki!...8 4.3 Yksikkötestit...8 4.4 Raporttien ja dokumentaation julkaisu...8 4.4.1 Staattiset analyysityökalut...8 4.4.2 Dokumenttien julkaisu...9 4.5 Buildiskriptin rakenne...9 Aihe: CruiseControl ja AgilElephant Sivu 3 of 9
1. Esittely Tässä dokumentissa esitellään lyhyesti AgilElephant-projektissa käytetty automaattinen buildijärjestelmä, CruiseControl ja se miten sitä on sovellettu. 1.1 Tarkoitus Dokumentin tarkoituksena on listata buildijärjestelmän toiminnot riippuvuuksineen ja kertoa miten CruiseControlia on käytetty projektin aikana. Aihe: CruiseControl ja AgilElephant Sivu 4 of 9
2. Johdanto CruiseControl [http://cruisecontrol.sourceforge.net/] (jatkossa CC) on ilmainen avoimen lähdekoodin ohjelmisto, joka toteuttaa ns. jatkuvan buildiprosessin. Lainaus suoraan CC:n sivuilta: CruiseControl is a framework for a continuous build process. It includes, but is not limited to, plugins for email notification, Ant, and various source control tools. A web interface is provided to view the details of the current and previous builds. Jatkuvasta integraatiosta sanotaan seuraavaa: An important part of any software development process is getting reliable builds of the software. Despite its importance, we are often surprised when this isn't done. We stress a fully automated and reproducible build, including testing, that runs many times a day. This allows each developer to integrate daily thus reducing integration problems. Tämän ideologian pohjalta lähdin asiakkaalta vinkin saatuani toteuttamaan projektillemme automaattista buildijärjestelmää. Taustalla oli kokemus miten turhauttavaa voi olla kun ohjelmisto ei käänny kokonaan ja miten paljon tämä voi haitata työskentelyä. Kokemusta oli myös omassa työpaikassani käytössä olevasta systeemistä, joka lähettää sähköpostia buildin ollessa rikki. Aihe: CruiseControl ja AgilElephant Sivu 5 of 9
3. Käyttöönotto Järjestelmän käyttöönotto on suhteellisen suoraviivaista kunhan muistaa seurata ohjeita. Tässä kohtaa apuna toimii CC:n oma Getting Started dokumentaatio [http://cruisecontrol.sourceforge.net/gettingstarted.html], joka on kirjoitettu melko hyvin. Käyttöönoton vaativin osuus on ehkäpä esivaatimusten varmistaminen. Lyhyesti listattuna projektin tulisi olla rakennettavissa jollakin tuetulla työkalulla ja yhdellä targetilla o Javan kohdalla tämä tarkoittaa esim. Antia ja yhtä korkean tason targetia tossakin tuetussa versionhallintajärjestelmässa o meidän tapauksessamme CVS Lisäksi tarvitaan Java-kääntäjä ja jokin Java-sovelluspalvelin, jossa raporttisivut ovat selattavissa. Me käytimme JBossia, koska se on ilmainen ja sisältää Tomcatin. Lisäksi AgilElephant rakennettiin pyörimään JBossin päälle jolloin samaa palvelinta voitiin käyttää CC:n ja demojärjestelmän ajamiseen. Tarkemmat ohjeet CC: kääntämisestä ja konfiguroinnista kannattaa lukea suoraan järjestelmän omasta ohjeesta. Aihe: CruiseControl ja AgilElephant Sivu 6 of 9
4. CruiseControl ja AgilElephant AgilElephantin tapauksessa CC:stä rakentui lopulta melko kattava automaatti, joka teki paljon muutakin kuin ilmoitti rikkinäisestä koodista. Lisäksi järjestelmä asennettiin automaattisesti JBossin alle käyntiin, ajettiin yksikkötestit, generoitiin koodimetriikoita ja raportteja sekä julkaistiin javadocit ja muut projektin dokumentit. 4.1 Kääntäminen ja asennus Koska käyttämämme buildityökalu oli Ant, teimme AgilElephantille build.xml tiedoston joka sisälsi kaikki automatisoitavat toiminnot. CruiseControlin tehtävänä oli tarkistaa onko CVS:ssä tapahtunut muutoksia ja jos oli niin päivittää kaikki tiedostot ja kääntää järjestelmä. Tarkistusväliksi tuli 10 minuuttia ja suoritettava target oli nimeltään test-all. Alkuvaiheessa suurta päänvaivaa aiheutti se, että CC ei tuntunut huomaavan muutoksia. Syy löytyi lopulta käytetystä CVS-clientista, joka ei toiminut oikein kun CVS-palvelin oli eri aikavyöhykkeellä. Ratkaisuna muokkasin CC:n CVS-käsitelijää (main\src\net\sourceforge\cruisecontrol\sourcecontrols\cvs.java) huomioimaan palvelimien välisen kahden tunnin aikaeron. Mielenkiintoisena yksityiskohtana mainittakoon, että CC/demopalvelin sijaitsee fyysisesti Floridassa, mutta sen kello käy Greenwichin aikaa. Ruma koodinmuutos on listattu alla (lisäykset kursiivilla): //AgilElephant long offset = 2 * 3600 * 1000; // 2h long time = lastbuildtime.gettime(); time -= offset; lastbuildtime.settime(time); //AgilElephant String daterange = formatcvsdate(lastbuildtime) + "<" + formatcvsdate(checktime); commandline.createargument().setvalue("-d" + daterange); //AgilElephant time += offset; lastbuildtime.settime(time); //AgilElephant Tämän muutoksen jälkeen CVS-aktiviteetit havaittiin oikein ja CC pyöräytti buildin jokaisen muutoksen jälkeen. 4.2 Tietokannan puhdistus ja alustus Koska tietokantarakenne muuttui varsinkin projektin alkuvaiheessa useasti koettiin tarpeelliseksi automatisoida kantarakenteen päivittäminen. Tämän Ant-taskin nimi oli recreate-db ja se tuhosi olemassaolevat taulut, loi kaikki taulut uudestaan, ajoi sisälle perusdataa kuten käyttäjät sekä vielä lisäksi ajoi sisälle testidataa. Kannan kuvaus ja sisältö oli CVS:ssä erillisissä sql-tiedostoissa. Koska kyseessä ei ole aivan tavallinen Ant/CC-taski on koodi listattu alla: <target name="recreate-db" description="drops and recreates the db-tables with the init data"> <property name="db_exe" value="c:/mysql/bin/mysql.exe"/> <property name="db_name" value="agile"/> <property name="db_user" value="db-käyttäjä"/> <property name="db_pass" value="db-salasana"/> <property name="db_out" value="${basedir}/db.log"/> Aihe: CruiseControl ja AgilElephant Sivu 7 of 9
<property name="sqldir" location="${basedir}/sql"/> <property name="create_script" value="recreate.sql"/> <concat destfile="${basedir}/${create_script}"> <filelist dir="${sqldir}" files="drop.sql, agile.sql, basedata.sql, testdata.sql"/> </concat> <exec dir="${basedir}" executable="${db_exe}" output="${db_out}"> <arg line="--user=${db_user} --password=${db_pass} --database=${db_name} -e "source ${create_script}""/> </exec> </target> Projektin loppuvaiheessa tietokannan rakenne jäädytettiin ja tämä tehtävä poistettiin kokonaan buildiskriptistä vahinkojen välttämiseksi tuotantoympäristössä. 4.2.1 Buildi on rikki! Buildirikon sattuessa CC konfiguroitiin lähettämään postia projektiryhmän postituslistalle. Sähköpostin sisältönä oli vain ilmoitus tapahtuneesta sekä linkki varsinaiselle raporttisivulle. Kun vika oli korjattu CC lähetti uuden tiedotteen, jossa kerrottiin, että buildi toimii taas. 4.3 Yksikkötestit Kun uunituore järjestelmä oli käännetty ja alustettu oli aika ajaa yksikkötestit. Koska CC on tehty yksikkötestejä silmällä pitäen riittää kun testit ajetaan käännöksen yhteydessä ja testien lokitiedoston sijainti kerrotaan CC:lle. <log dir="logs/agil" encoding="iso-8859-1"> <merge file="checkout/test/final_report.xml"/> </log> ISO-8859-1 merkistön käyttö on suositeltavaa, koska jostain syystä UTF-8:aa käytettäessä CC tulkitsi kaikki lokit roskaksi. Testien epäonnistumisesta ei tullut erillistä ilmoitusta, koska päivittäinen seuranta osoittautui riittäväksi. Samalla vältyttiin myös turhilta virheilmoituksilta, koska joskus testit epäonnistuivat sen takia, että JBoss ei ollut ehtinyt lataamaan koko sovellusta kun testien ajaminen alkoi. Tämä ratkesi lopulta lisäämällä deploy-kutsun jälkeen komento <sleep seconds="30"/>. 4.4 Raporttien ja dokumentaation julkaisu 4.4.1 Staattiset analyysityökalut Projektissa käytettiin kokeiluluontoisesti työkaluja tyypillisten ohjelmointivirheiden etsimiseen (FindBugs) sekä koodin kompleksisuuden analysointiin (JavaNCSS). Molemmille tehtiin omat Ant-tehtävät, jotka yhdistettiin reports-tehtäväksi. Lisäksi käytössä oli StatCVS-ohjelma CVS-tilastojen keräämiseksi, mutta se ei kuormittavuutensa takia ollut mukana automaattisessa ajossa. Aihe: CruiseControl ja AgilElephant Sivu 8 of 9
4.4.2 Dokumenttien julkaisu 4.4.2.1 Javadoc Projektin loppuvaiheessa aloimme generoimaan ja julkaisemaan myös koko järjestelmämme Javadocit webissä automaattisesti. Ant tukee tätä joten sen toteuttaminen oli suoraviivaista. 4.4.2.2 Muut dokumentit Koska kaikki projektin dokumentaatio oli CVS:ssä oli uusimpien versioiden julkaiseminen yhtä helppoa kuin niiden kopioiminen webbipalvelimen julkaistavaksi sopivalla indeksisivulla. 4.5 Buildiskriptin rakenne Kuvassa 1 on esitetty buildiprosessin hierarkia. Kuva 1: Eri Ant-tehtävien kutsupuu. Järjestys vasemmalta oikealle Aihe: CruiseControl ja AgilElephant Sivu 9 of 9