サンプルコードで身につける: Ant: build.xml を1行ずつ読む

解説で学んだ概念を、5つの具体例で確認します。素朴な例から実務寄りの例へと進みます。

1build.xml の全文(73行): 前のレッスンの5段を5つの target に

前のレッスンで手でやった5段を、そのままにしたです。塗ってあるのは、本文と5本目の表で説明している要素の行です。読む順は、の ="" から、jar の ="test"、test の depends="compile,resources"、compile と resources の depends="init"、init と辿ります。各 target の中の、copy、、jar、の行と、冒頭の、path の行も塗ってあります。属性の ${…} は property の値に置き換えて読みます。

build.xml(l2-ant/app、Ant 1.10.18 で実行確認)設定ファイル

<project name="app" default="jar" basedir=".">
    <description>The five hand-made steps of l1-manual, written as Ant targets</description>
 
    <property name="src.dir"       location="src"/>
    <property name="res.dir"       location="resources"/>
    <property name="test.dir"      location="test"/>
    <property name="lib.dir"       location="lib"/>
    <property name="classes.dir"   location="build/classes"/>
    <property name="test.classes.dir" location="build/test-classes"/>
    <property name="dist.dir"      location="dist"/>
 
    <path id="compile.classpath">
        <fileset dir="${lib.dir}" includes="*.jar"/>
    </path>
    <path id="test.classpath">
        <path refid="compile.classpath"/>
        <fileset dir="lib-test" includes="*.jar"/>
        <pathelement location="${classes.dir}"/>
    </path>
 
    <target name="clean" description="delete build/ and dist/">
        <delete dir="build"/>
        <delete dir="${dist.dir}"/>
    </target>
 
    <target name="init">
        <mkdir dir="${classes.dir}"/>
        <mkdir dir="${test.classes.dir}"/>
        <mkdir dir="${dist.dir}"/>
        <mkdir dir="build/test-reports"/>
    </target>
 
    <target name="compile" depends="init" description="(a) javac src/ -> build/classes/">
        <javac srcdir="${src.dir}" destdir="${classes.dir}" classpathref="compile.classpath"
               includeantruntime="false" debug="true"/>
    </target>
 
    <target name="resources" depends="init" description="(b) copy resources/ -> build/classes/">
        <copy todir="${classes.dir}">
            <fileset dir="${res.dir}"/>
        </copy>
    </target>
 
    <target name="test" depends="compile,resources" description="(c) compile and run the JUnit 5 tests">
        <javac srcdir="${test.dir}" destdir="${test.classes.dir}" classpathref="test.classpath"
               includeantruntime="false" debug="true"/>
        <junitlauncher printsummary="true" haltOnFailure="true">
            <classpath refid="test.classpath"/>
            <classpath><pathelement location="${test.classes.dir}"/></classpath>
            <testclasses outputdir="build/test-reports">
                <fileset dir="${test.classes.dir}"/>
                <listener type="legacy-plain" sendSysOut="true"/>
            </testclasses>
        </junitlauncher>
    </target>
 
    <target name="jar" depends="test" description="(d) build/classes/ -> dist/app.jar">
        <jar destfile="${dist.dir}/app.jar" basedir="${classes.dir}">
            <manifest>
                <attribute name="Main-Class" value="com.example.app.Main"/>
            </manifest>
        </jar>
    </target>
 
    <target name="run" depends="jar" description="(e) run with the dependency on the classpath">
        <java classname="com.example.app.Main" fork="true" failonerror="true">
            <classpath>
                <pathelement location="${dist.dir}/app.jar"/>
                <path refid="compile.classpath"/>
            </classpath>
        </java>
    </target>
</project>

2ant -p と、ant run の1回目・2回目

はのある target を並べ、最後に default を出します。このファイルには description のある target があるので、無い init は出ません。 run の1回目は init から順に6つの target が走り、2回目は compile、resources、jar の見出しだけで何もしません。test だけは毎回走ります。junitlauncher のには済んでいるかの判定が無いからです。

$ ant -p / $ ant run(1回目と2回目)コマンド出力

$ ant -p                                # description のある target が1つでもあるので、無い init は出ない
Buildfile: /bt/l2-ant/app/build.xml
The five hand-made steps of l1-manual, written as Ant targets
Main targets:
 
 clean      delete build/ and dist/
 compile    (a) javac src/ -> build/classes/
 jar        (d) build/classes/ -> dist/app.jar
 resources  (b) copy resources/ -> build/classes/
 run        (e) run with the dependency on the classpath
 test       (c) compile and run the JUnit 5 tests
Default target: jar
 
$ ant run                               # 1回目。depends を辿って init から順に
Buildfile: /bt/l2-ant/app/build.xml
 
init:
    [mkdir] Created dir: /bt/l2-ant/app/build/classes
    [mkdir] Created dir: /bt/l2-ant/app/build/test-classes
    [mkdir] Created dir: /bt/l2-ant/app/dist
    [mkdir] Created dir: /bt/l2-ant/app/build/test-reports
 
compile:
    [javac] Compiling 2 source files to /bt/l2-ant/app/build/classes
 
resources:
     [copy] Copying 1 file to /bt/l2-ant/app/build/classes
 
test:
    [javac] Compiling 1 source file to /bt/l2-ant/app/build/test-classes
[junitlauncher] Running com.example.greet.GreeterTest
[junitlauncher] Tests run: 1, Failures: 0, Aborted: 0, Skipped: 0, Time elapsed: 0.035 sec
 
jar:
      [jar] Building jar: /bt/l2-ant/app/dist/app.jar
 
run:
     [java] Hello, World!
 
BUILD SUCCESSFUL
 
$ ant run                               # 2回目。何も変えていない
Buildfile: /bt/l2-ant/app/build.xml
 
init:
 
compile:
 
resources:
 
test:
[junitlauncher] Running com.example.greet.GreeterTest
[junitlauncher] Tests run: 1, Failures: 0, Aborted: 0, Skipped: 0, Time elapsed: 0.028 sec
 
jar:
 
run:
     [java] Hello, World!
 
BUILD SUCCESSFUL

3property の値を見る: -v では出ず、-d で出る。-D は先に決まる

property の名前と値の対応はには出ません(展開済みのパスが javac の引数などに現れるだけです)。にすると Setting project property: の行で名前と展開済みの絶対パスが見えます。コマンドラインの -Ddist.dir=… は build.xml より先に設定されるので、build.xml 側の <property> は Override ignored と無視され、dist/ は作られませんでした。

$ ant -d / $ ant -Ddist.dir=/tmp/elsewhere jar(29行版の build.xml)コマンド出力

# 29行版の build.xml(レッスン「ant を実行すると何が起きるか」のもの)で確認
#   <property name="src.dir"   location="src"/>
#   <property name="build.dir" location="build/classes"/>
#   <property name="dist.dir"  location="dist"/>
 
$ ant -v | grep -n -i "property\|build.dir\|/bt/l2-ant/plain/build\|Build sequence"
3:Buildfile: /bt/l2-ant/plain/build.xml
6:parsing buildfile /bt/l2-ant/plain/build.xml with URI = file:/bt/l2-ant/plain/build.xml
9:Build sequence for target(s) `jar' is [init, compile, jar]
10:Complete build sequence is [init, compile, jar, clean, ]
13:    [mkdir] Created dir: /bt/l2-ant/plain/build/classes
19:    [javac] Compiling 2 source files to /bt/l2-ant/plain/build/classes
23:    [javac] '/bt/l2-ant/plain/build/classes'
25:    [javac] '/bt/l2-ant/plain/build/classes'
47:      [jar] Location: /bt/l2-ant/plain/build.xml:23: 
# 展開済みのパスは出るが、「名前 -> 値」の設定行は -v には1行も無い
 
$ ant -d clean 2>&1 | grep -i "Setting .*property\|Override ignored\|build.dir\|dist.dir\|src.dir" | head -40
Setting ro project property: ant.file -> /bt/l2-ant/plain/build.xml
...
Setting ro project property: ant.project.name -> hello
Setting ro project property: ant.project.default-target -> jar
...
Setting project property: src.dir -> /bt/l2-ant/plain/src
Setting project property: build.dir -> /bt/l2-ant/plain/build/classes
Setting project property: dist.dir -> /bt/l2-ant/plain/dist
...
 
$ ant -Ddist.dir=/tmp/elsewhere jar && ls -l /tmp/elsewhere dist 2>&1    # コマンドラインで dist.dir を上書き
init:
    [mkdir] Created dir: /bt/l2-ant/plain/build/classes
    [mkdir] Created dir: /tmp/elsewhere
 
compile:
    [javac] Compiling 2 source files to /bt/l2-ant/plain/build/classes
 
jar:
      [jar] Building jar: /tmp/elsewhere/app.jar
 
BUILD SUCCESSFUL
Total time: 0 seconds
ls: cannot access 'dist': No such file or directory
/tmp/elsewhere:
total 4
-rw-r--r-- 1 root root 1680 Oct  3 00:21 app.jar
 
$ ant -d -Ddist.dir=/tmp/elsewhere2 init 2>&1 | grep -i "dist.dir"
Setting ro project property: dist.dir -> /tmp/elsewhere2
Override ignored for property "dist.dir"

4depends の順序: 1つの呼び出しでは1回、2つ並べると2回

D が B と C に、B と C が A に依存する形で、ant D なら A は1回です。マニュアルの例と同じ depends="C,B,A" を持つ E は、B と C が A にだけ依存するこの形では、左から右に、ただし依存が先になるよう並べ直されて A, C, B, E になりました(マニュアルの例は C→B→A の鎖なので、そちらは A, B, C, D です。build.xml のコメントはその depends を借りたという意味です)。ant B C と2つ並べると、呼び出しごとに記録が切れて A が2回走ります。下のコードは、この2つの規則と property の凍結を素の Java でなぞった模型です。

diamond/build.xml と $ ant / $ ant -v D / $ ant E / $ ant B Cコマンド出力

# build.xml(diamond)
<project name="diamond" default="D">
    <!-- D depends on B and C; both depend on A. How many times does A run? -->
    <target name="A"><echo>A runs</echo></target>
    <target name="B" depends="A"><echo>B runs</echo></target>
    <target name="C" depends="A"><echo>C runs</echo></target>
    <target name="D" depends="B,C"><echo>D runs</echo></target>
    <!-- the manual's own example: depends="C,B,A" -->
    <target name="E" depends="C,B,A"><echo>E runs</echo></target>
</project>
 
$ ant                                   # default="D"。A は1回
A:
     [echo] A runs
 
B:
     [echo] B runs
 
C:
     [echo] C runs
 
D:
     [echo] D runs
 
BUILD SUCCESSFUL
 
$ ant -v D | grep "Build sequence"
Build sequence for target(s) `D' is [A, B, C, D]
 
$ ant -v E | grep "Build sequence"     # E depends="C,B,A"。B と C は A にだけ依存するので A, C, B, E
Build sequence for target(s) `E' is [A, C, B, E]
 
$ ant B C                               # target を2つ並べると A が2回
A:
     [echo] A runs
 
B:
     [echo] B runs
 
A:
     [echo] A runs
 
C:
     [echo] C runs
 
BUILD SUCCESSFUL
 
$ ant -p                                # description が無いので全部 Other targets
Main targets:
 
Other targets:
 
 A
 B
 C
 D
 E
Default target: D

Java

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

// build.xml の2つの規則の模型(Ant の実装ではない):
//  1. depends は「先に実行する target」。1回の呼び出しの中では、同じ target は1回しか実行されない。
//     ただし ant B C のように target を2つ並べると、呼び出しごとに実行済みの記録がリセットされる。
//  2. property は「先に決めた者が凍結する」。後から同じ名前を <property> で設定しても無視される。
class Main {
    // target 名 -> depends(左から右の順)
    static final Map<String, List<String>> DEPENDS = new LinkedHashMap<>();

    static void target(String name, String... depends) {
        DEPENDS.put(name, List.of(depends));
    }

    // 1回の呼び出し。実行済みの記録(done)は呼び出しの中だけで共有する
    static void invoke(String name, List<String> done, List<String> sequence) {
        if (done.contains(name)) {
            return;
        }
        for (String before : DEPENDS.get(name)) {
            invoke(before, done, sequence);
        }
        done.add(name);
        sequence.add(name);
    }

    // ant <targets...> の模型: 並べた target ごとに別の呼び出しになる
    static void ant(String... targets) {
        System.out.print("$ ant");
        for (String t : targets) {
            System.out.print(" " + t);
        }
        System.out.println();
        for (String t : targets) {
            List<String> sequence = new ArrayList<>();
            invoke(t, new ArrayList<>(), sequence);
            System.out.println("   build sequence for " + t + " is " + sequence);
        }
    }

    // property の模型: 最初に設定した値だけが残る
    static final Map<String, String> PROPS = new LinkedHashMap<>();

    static void property(String name, String value, String who) {
        if (PROPS.containsKey(name)) {
            System.out.println("   Override ignored for property \"" + name + "\" (" + who + " tried " + value + ")");
            return;
        }
        PROPS.put(name, value);
        System.out.println("   Setting property: " + name + " -> " + value + " (" + who + ")");
    }

    public static void main(String[] args) {
        // D depends="B,C"、B と C は depends="A"(ダイヤモンド)
        target("A");
        target("B", "A");
        target("C", "A");
        target("D", "B", "C");
        // マニュアルと同じ depends="C,B,A" を、B と C が A にだけ依存するこの形で書くとどうなるか
        // (マニュアルの例は C→B→A の鎖なので、そちらは A, B, C, D になる)
        target("E", "C", "B", "A");

        System.out.println("## 1. depends: once per invocation");
        ant("D");       // A は1回
        ant("E");       // 左から右、ただし依存が先: A, C, B, E
        ant("B", "C");  // 2つ並べると A が2回
        System.out.println();

        System.out.println("## 2. property: first setter wins");
        // コマンドラインの -D は build.xml より先に設定される
        property("dist.dir", "/tmp/elsewhere", "-Ddist.dir on the command line");
        property("dist.dir", "dist", "<property> in build.xml");
        property("src.dir", "src", "<property> in build.xml");
        System.out.println("   final: " + PROPS);
    }
}

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;

// build.xml の2つの規則の模型(Ant の実装ではない):
//  1. depends は「先に実行する target」。1回の呼び出しの中では、同じ target は1回しか実行されない。
//     ただし ant B C のように target を2つ並べると、呼び出しごとに実行済みの記録がリセットされる。
//  2. property は「先に決めた者が凍結する」。後から同じ名前を <property> で設定しても無視される。
class Main {
    // target 名 -> depends(左から右の順)
    static final Map<String, List<String>> DEPENDS = new LinkedHashMap<>();

static void target(String name, String... depends) {
        DEPENDS.put(name, List.of(depends));
    }

// 1回の呼び出し。実行済みの記録(done)は呼び出しの中だけで共有する
    static void invoke(String name, List<String> done, List<String> sequence) {
        if (done.contains(name)) {
            return;
        }
        for (String before : DEPENDS.get(name)) {
            invoke(before, done, sequence);
        }
        done.add(name);
        sequence.add(name);
    }

// ant <targets...> の模型: 並べた target ごとに別の呼び出しになる
    static void ant(String... targets) {
        System.out.print("$ ant");
        for (String t : targets) {
            System.out.print(" " + t);
        }
        System.out.println();
        for (String t : targets) {
            List<String> sequence = new ArrayList<>();
            invoke(t, new ArrayList<>(), sequence);
            System.out.println("   build sequence for " + t + " is " + sequence);
        }
    }

// property の模型: 最初に設定した値だけが残る
    static final Map<String, String> PROPS = new LinkedHashMap<>();

static void property(String name, String value, String who) {
        if (PROPS.containsKey(name)) {
            System.out.println("   Override ignored for property \"" + name + "\" (" + who + " tried " + value + ")");
            return;
        }
        PROPS.put(name, value);
        System.out.println("   Setting property: " + name + " -> " + value + " (" + who + ")");
    }

public static void main(String[] args) {
        // D depends="B,C"、B と C は depends="A"(ダイヤモンド)
        target("A");
        target("B", "A");
        target("C", "A");
        target("D", "B", "C");
        // マニュアルと同じ depends="C,B,A" を、B と C が A にだけ依存するこの形で書くとどうなるか
        // (マニュアルの例は C→B→A の鎖なので、そちらは A, B, C, D になる)
        target("E", "C", "B", "A");

System.out.println("## 1. depends: once per invocation");
        ant("D");       // A は1回
        ant("E");       // 左から右、ただし依存が先: A, C, B, E
        ant("B", "C");  // 2つ並べると A が2回
        System.out.println();

System.out.println("## 2. property: first setter wins");
        // コマンドラインの -D は build.xml より先に設定される
        property("dist.dir", "/tmp/elsewhere", "-Ddist.dir on the command line");
        property("dist.dir", "dist", "<property> in build.xml");
        property("src.dir", "src", "<property> in build.xml");
        System.out.println("   final: " + PROPS);
    }
}

5要素・属性の早見表: 職場の build.xml で出会うもの

73行版に出てくる要素と属性を、 1.10.18 のマニュアルの原文、73行版の該当する行、Node 側で近いもの(たとえ)の順に並べました。project から java まで、1本目の build.xml で塗ってある行と対応しています。マニュアルの逐語を取っていない java の task だけは、実測で分かることにとどめています。

build.xml の要素・属性の早見表(Ant 1.10.18)表