mirror of https://github.com/apache/ant-ivy
115 lines
5.3 KiB
Plaintext
115 lines
5.3 KiB
Plaintext
////
|
|
Licensed to the Apache Software Foundation (ASF) under one
|
|
or more contributor license agreements. See the NOTICE file
|
|
distributed with this work for additional information
|
|
regarding copyright ownership. The ASF licenses this file
|
|
to you under the Apache License, Version 2.0 (the
|
|
"License"); you may not use this file except in compliance
|
|
with the License. You may obtain a copy of the License at
|
|
|
|
https://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing,
|
|
software distributed under the License is distributed on an
|
|
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
KIND, either express or implied. See the License for the
|
|
specific language governing permissions and limitations
|
|
under the License.
|
|
////
|
|
|
|
[*__since 2.0__*]
|
|
|
|
The settings declaration is used to configure Ivy with a settings XML file. The difference with the link:../use/configure{outfilesuffix}[configure] task is that when using the settings declaration, the configuration of Ivy will be done when the settings are first needed (for instance, when you do a resolve), while the configure task will perform a configuration of Ivy instantly, which makes it easier to see the problem if something goes wrong.
|
|
|
|
See link:../settings{outfilesuffix}[Settings Files] for details about the settings file itself.
|
|
|
|
Multiple settings can be defined in a build script. Every task can reference its own settings.
|
|
|
|
All Ivy variables set during the settings are available in the Ant project as long as they were not set in Ant before (Ant properties are immutable).
|
|
|
|
Moreover, the variables are exposed under two names: the variable name, and the variable name suffixed by dot + the settings id.
|
|
|
|
For instance, if you load a settings with the id `myid`, and define a variable `my.variable=my.value` in the Ivy settings, both `my.variable` and `my.variable.myid` will now be available as properties in Ant and equal to `my.value`. If you later load another settings with the id `yourid`, and in this settings assign the variable `my.variable` the value `your.value`, in the Ant project you will have:
|
|
[source,properties]
|
|
----
|
|
my.variable=my.value
|
|
my.variable.myid=my.value
|
|
my.variable.yourid=your.value
|
|
----
|
|
|
|
== Attributes
|
|
|
|
[options="header",cols="15%,50%,35%"]
|
|
|=======
|
|
|Attribute|Description|Required
|
|
|id|The settings id usable in the `settingsRef` attributes of the Ivy task that needs a setting.|No, defaults to `ivy.instance`
|
|
|file|path to the settings file to use
|
|
.2+.^|No. If a file is provided, URL is ignored. If none are provided, then it attempts to find a file at `${ivy.settings.file}`, and if this file does not exist, it uses a link:../tutorial/defaultconf{outfilesuffix}[default settings file]
|
|
|url|URL of the settings file to use
|
|
|host|HTTP authentication host
|
|
.4+.^|No, unless authentication is required
|
|
|realm|HTTP authentication realm
|
|
|username|HTTP authentication user name
|
|
|passwd|HTTP authentication password
|
|
|=======
|
|
|
|
== HTTP Authentication
|
|
|
|
__Note__: HTTP authentication can be used only if link:https://hc.apache.org/httpcomponents-client-ga/index.html[HttpComponents HttpClient library] (minimum of 4.5.3 version) and its link:https://hc.apache.org/httpcomponents-client-4.5.x/dependency-management.html[dependencies] are in your classpath.
|
|
|
|
If any of the URLs you use in Ivy (especially in dependency resolvers) needs HTTP authentication, then you have to provide the `host`, `realm`, `username` and `passwd` attributes of the configure task. These settings will then be used in any further call to Ivy tasks.
|
|
|
|
== Multiple classloader
|
|
|
|
A special attention should be applied when you have a multi-project build with `subant` call, using Ivy task loaded by a `typedef`. Indeed in this situation, it is possible to pass settings reference to a subbuild. When you do that, you should take care of the classloader. The Ivy task of your `subant` should not be defined in a different classloader than the parent one. This can be achieved by using the `loader` parameter of the antlib declaration, or avoid to reload the Ivy antlib in the subbuild (place the `taskdef` in a target only executed when the antlib is not yet loaded).
|
|
|
|
== Examples
|
|
|
|
=== Simplest settings
|
|
|
|
[source,xml]
|
|
----
|
|
<ivy:settings/>
|
|
----
|
|
|
|
Use either `${ivy.settings.file}` if it exists, or the link:../samples/ivysettings-default.xml[default settings file]
|
|
|
|
This simplest setting is implicit.
|
|
|
|
=== Configure with a file
|
|
|
|
[source,xml]
|
|
----
|
|
<ivy:settings file="mysettings.xml"/>
|
|
----
|
|
|
|
=== Configure with an URL
|
|
|
|
[source,xml]
|
|
----
|
|
<ivy:settings url="http://mysite.com/mysettings.xml"/>
|
|
----
|
|
|
|
=== Configure multiple realms which require authentication
|
|
|
|
[source,xml]
|
|
----
|
|
<ivy:settings file="path/to/my/ivysettings.xml">
|
|
<credentials host="myhost.com" realm="My Realm" username="myuser" passwd="mypasswd"/>
|
|
<credentials host="yourhost.com" realm="Your Realm" username="myuser" passwd="myotherpasswd"/>
|
|
</ivy:settings>
|
|
----
|
|
|
|
=== Configure 2 different settings
|
|
|
|
You can use multiple Ivy settings during a build. Then every Ivy task should specify the settings it uses using the `settingsRef` attribute.
|
|
|
|
[source,xml]
|
|
----
|
|
<ivy:settings id="ivy.normal.settings" file="normal_settings.xml"/>
|
|
<ivy:settings id="ivy.release.settings" file="release_settings.xml"/>
|
|
|
|
<ivy:resolve settingsRef="ivy.normal.settings"/>
|
|
<ivy:resolve settingsRef="ivy.release.settings"/>
|
|
----
|