File: README.md

package info (click to toggle)
aether-ant-tasks 1.0.1-4
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 632 kB
  • sloc: java: 5,123; xml: 1,133; makefile: 2
file content (244 lines) | stat: -rw-r--r-- 9,153 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# Aether Ant Tasks

The Aether Ant Tasks enable build scripts for [Apache Ant](http://ant.apache.org/) 1.7+ to use 
[Eclipse Aether](http://www.eclipse.org/aether) combined to
[Apache Maven Aether Provider](http://maven.apache.org/ref/current/maven-aether-provider/) to resolve dependencies
and install and deploy locally built artifacts.

To integrate the tasks into your build file, copy the JAR into your project's lib directory and use the following
snippet to load it:

    <project xmlns:aether="antlib:org.eclipse.aether.ant" ...>
      <taskdef uri="antlib:org.eclipse.aether.ant" resource="org/eclipse/aether/ant/antlib.xml">
        <classpath>
          <fileset dir="lib" includes="aether-ant-tasks-*.jar"/>
        </classpath>
      </taskdef>
      ...
    </project>

See the build.xml in the project sources for a complete example build script.

## Settings

The Ant tasks are tightly integrated with the usual [Apache Maven settings.xml](http://maven.apache.org/settings.html).
By default, the usual ${user.home}/.m2/settings.xml is used for user settings. 

For the global settings, different paths will be tried:

* ${ant.home}/etc/settings.xml
* ${maven.home}/conf/settings.xml
* $M2_HOME/conf/settings.xml

The <settings/> definition is used to change that:
    
    <settings file="my-settings.xml" globalfile="myglobal-settings.xml"/>

Some settings defined in the settings file or in the POM can also be changed inside the Ant file.

### Proxy Settings

Proxy definitions are used throughout the whole session. There may be multiple
proxies set. The proxy to use will be chosen by evaluating the nonProxyHosts on
each proxy definition, the first matching proxy will be used for a given remote connection.

    <proxy host="proxy.mycorp.com" port="8080" type="http" nonProxyHosts="127.*|localhost|*.mycorp.com"/>

### Authentication

Authentication elements are used to access remote repositories. Every
authentication definition will be added globally and chosen based on the
'servers' attribute. If this attribute is not set, an authentication has to be
referenced explicitly to be used.

    <authentication username="login" password="pw" id="auth"/>
    <authentication privateKeyFile="file.pk" passphrase="phrase" servers="distrepo" id="distauth"/>

### Local Repository

Only one local repository can be used at a time.

    <localrepo dir="someDir"/>

### Remote Repositories

Remote repositories may be defined directly:

    <remoterepo id="ossrh" url="https://oss.sonatype.org/content/repositories/snapshots/" type="default" releases="false" snapshots="true" updates="always" checksums="fail"/>

    <remoterepo id="rao" url="https://repository.apache.org/content/groups/public/">
        <releases enabled="true" updates="daily" checksums="warn"/>
        <snapshots enabled="false"/>
        <authentication refid="auth"/>
    </remoterepo>

    <remoterepo id="distrepo" url="..." authref="distauth"/>

Multiple repositories may be used as a group in every place that is legal for a
remote repository:

    <remoterepos id="all">
        <remoterepo refid="ossrh"/>
        <remoterepo refid="rao"/>
        <remoterepo refid="distrepo"/>
    </remoterepos>

*Note:* Currently, only file:, http: and https: protocols are supported for remote repositories.

### Mirrors

    <mirror id="" url="" mirrorOf=""/>

### Offline Mode

To suppress any network activity and only use already cached artifacts/metadata, you can use a boolean property:

    <property name="aether.offline" value="true"/>


## Project

Project settings deal with locally availabe information about the build.

### POM

The POM is the data type used to determine the target for the install and
deploy tasks. If you define a POM without an id based on a full pom.xml file,
that POM will be used by default for install and deploy.

    <pom file="pom.xml" id="pom"/>
    <pom groupId="g" artifactId="a" version="v"/>
    <pom coords="g:a:v"/>

#### Properties

If a POM is set via a file parameter its effective model is made available as properties to the Ant project.
The properties are prefixed with the ref id of the `<pom>` element, e.g. ${pom.version} for the example above.
Likewise, project properties defined in the POM are accessible via the prefix "pom.properties.". If no id has been
assigned, the properties use the prefix "pom." by default.

### Output Artifacts

`<artifact>` elements define the artifacts produced by this build that should be installed or deployed.

    <artifact file="file-src.jar" type="jar" classifier="sources" id="src"/>

    <artifacts id="producedArtifacts">
        <artifact refid="src"/>
        <artifact file="file-src.jar"/>
    </artifacts>

### Dependencies

Dependencies are used to to create classpaths or filesets. They are used by
the `<resolve>`-task, which collects the artifacts belonging to the dependencies
transitively.

    <dependency coords="g:a:v:scope"/>

    <dependency groupId="g" artifactId="a" version="v" classifier="c" type="jar" scope="runtime">
        <exclusion coords="g:a"/>
        <exclusion groupId="g" artifactId="a"/>
    </dependency>

    <dependencies id="deps">
        <dependency refid="first"/>
        <dependency refid="second"/>
        <exclusion coords="g:a"/> <!-- global exclusion for all dependencies of this group -->
    </dependencies>

    <dependencies>
        <dependency coords="test:artifact:1.0:runtime"/>
        <dependencies refid="deps"/> <!-- nested dependency collection merged into this one -->
    </dependencies>

    <dependencies id="depsFromPom" pomRef="pom"/>

    <dependencies id="depsFromPlainTextFile" file="dependencies.txt"/>
    <!--
    Each non-empty line of that text file declares one dependency, using the same syntax as for the `coords` attribute
    of the `<dependency>` element, i.e.
    <groupId>:<artifactId>:<version>[[:<type>[:<classifier>]]:<scope>]
    Everything after the first hash (#) character on a line is considered a comment.
    -->


## Tasks

### Install

You need to set a POM that references a file for the install task to work.

    <install artifactsref="producedArtifacts"/>

### Deploy

You need to set a POM that references a file for the deploy task to work, as that POM file will be deployed to repository.

    <deploy artifactsref="producedArtifacts">
        <remoterepo refid="distrepo"/>
        <snapshotrepo refid="snaprepo">
    </deploy>

### Resolve

The `<resolve>`-task is used to collect and resolve dependencies from remote
servers. If no repositories are set explicitly for the task, the repositories
referenced by "aether.repositories" are used. This contains only central by
default, but can be overridden by supplying another repository definition with
this id. 


This task is able to assemble the collected dependencies in three different ways:

* Classpath: The `<path>` element defines a classpath with all resolved dependencies.
* Files: `<files>` will assemble a resource collection containing all resolved dependencies and/or copy the files to some directory.
* Properties: `<properties>` will set properties with the given prefix and the coordinates to the path to the resolved file.

These targets may also be mentioned more than once for the same resolve task,
but only one `<dependencies>` element is allowed.

    <resolve failOnMissingAttachments="true">
        <dependencies>
            <dependency coords="org.apache.maven:maven-profile:2.0.6"/>
            <exclusion artifactId="junit"/>
            <exclusion groupId="org.codehaus.plexus"/>
        </dependencies>
        <path refid="cp" classpath="compile"/>
        <files refid="src.files" attachments="sources" dir="target/sources"
               layout="{artifactId}-{classifier}.{extension}"/>
        <files refid="api.files" attachments="javadoc" dir="target/javadoc"
               layout="{artifactId}-{classifier}.{extension}"/>
        <properties prefix="dep." scopes="provided,system"/>
    </resolve>

    <resolve dependenciesref="deps">
        <path refid="cp.compile" classpath="compile"/>
        <path refid="cp.test" classpath="test"/>
    </resolve>

Scope filters can be set on every target, enumerating included and/or excluded
scope names. Exclusions are denoted by prefixing the scope name with '-' or '!' (e.g. 'provided,!system').

The classpath attribute is a shortcut for the scope filters (e.g.
classpath="compile" equals scope="provided,system,compile"). Valid values are
"compile", "runtime", "test".

    <resolve>
        <dependencies pomRef="pom"/>
        <remoterepos refid="all"/>
        <path refid="cp" classpath="compile"/>
        <path refid="tp" classpath="test"/>
    </resolve>

The layout attribute of the `<files>` element is only allowed when the dir attribute is also given and recognizes the
following placeholders to refer to the coordinates of the currently processed artifact:

* {groupId}, e.g. "org.eclipse.aether"
* {groupIdDirs}, e.g. "org/eclipse/aether"
* {artifactId}, e.g. "aether-api"
* {version}, e.g. "1.0.0-20140518.181353-123"
* {baseVersion}, e.g. "1.0.0-SNAPSHOT"
* {extension}, e.g. "jar"
* {classifier}, e.g. "sources"