Repository: ant-ivy Updated Branches: refs/heads/master 2c435e5de -> fcc903775
[doc changes] Fix the documentation of the "OSGi" section Project: http://git-wip-us.apache.org/repos/asf/ant-ivy/repo Commit: http://git-wip-us.apache.org/repos/asf/ant-ivy/commit/fcc90377 Tree: http://git-wip-us.apache.org/repos/asf/ant-ivy/tree/fcc90377 Diff: http://git-wip-us.apache.org/repos/asf/ant-ivy/diff/fcc90377 Branch: refs/heads/master Commit: fcc90377525058b003dce832ad3854f087395e57 Parents: 2c435e5 Author: Jaikiran Pai <jaiki...@apache.org> Authored: Fri Jun 30 15:58:50 2017 +0530 Committer: Jaikiran Pai <jaiki...@apache.org> Committed: Fri Jun 30 15:58:50 2017 +0530 ---------------------------------------------------------------------- asciidoc/osgi.adoc | 4 +++- asciidoc/osgi/eclipse-plugin.adoc | 34 ++++++++++++--------------- asciidoc/osgi/osgi-mapping.adoc | 41 ++++++++++++++++----------------- asciidoc/osgi/sigil.adoc | 17 +++++++------- asciidoc/osgi/standard-osgi.adoc | 23 +++++++++++------- asciidoc/osgi/target-platform.adoc | 26 +++++++++++---------- 6 files changed, 75 insertions(+), 70 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi.adoc b/asciidoc/osgi.adoc index 51d2468..94d8b43 100644 --- a/asciidoc/osgi.adoc +++ b/asciidoc/osgi.adoc @@ -17,11 +17,13 @@ under the License. //// += OSGi + Since Apache Ivy™ 2.3, some support for OSGi™ dependency management has been introduced. -WARNING: Note that this feature is considered as *experimental*. It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. +WARNING: Note that this feature is considered as *experimental*. It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discuss your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found, on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. So with a standard ivy.xml, you can express some dependency on some OSGi bundle and every of their trasitive dependencies will be resolved. You can also declare in your ivy.xml some OSGi dependency, like a `Require-Bundle`, an `Import-Package` or an `Import-Service`, miming an OSGi MANIFEST.MF. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi/eclipse-plugin.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/eclipse-plugin.adoc b/asciidoc/osgi/eclipse-plugin.adoc index 183b1b1..d972c84 100644 --- a/asciidoc/osgi/eclipse-plugin.adoc +++ b/asciidoc/osgi/eclipse-plugin.adoc @@ -17,13 +17,13 @@ under the License. //// - += Building an Eclipse plugin [NOTE] ==== Note that this feature is considered as *experimental*. -It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. +It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discuss your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found, on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. ==== @@ -35,17 +35,15 @@ This page describes how to build an Eclipse™ plugin with Apache Ivy™ a In few steps, we will setup a build to compile and package an Eclipse plugin. + * download this link:../samples/eclipse-plugin/ivy.xml[ivy.xml], this link:../samples/eclipse-plugin/ivysettings.xml[ivysettings.xml], this link:../samples/eclipse-plugin/ivysettings.properties[ivysettings.properties], this link:../samples/eclipse-plugin/build.xml[build.xml], and put them into your plugin folder + * in the `ivysettings.properties`, specify the location of the plugins folder of your Eclipse target -. download this link:../samples/eclipse-plugin/ivy.xml[ivy.xml], this link:../samples/eclipse-plugin/ivysettings.xml[ivysettings.xml], this link:../samples/eclipse-plugin/ivysettings.properties[ivysettings.properties], this link:../samples/eclipse-plugin/build.xml[build.xml], and put them into your plugin folder; + - -. in the ivysettings.properties, specify the location of the plugins folder of your Eclipse target; + - -. in the ivy.xml, change the symbolic name declared in the extends element; + + * in the `ivy.xml`, change the symbolic name declared in the extends element -. __(optional)__ by default the build.xml is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case + + * *__(optional)__* by default the `build.xml` is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case -. __(optional)__ if Ivy is not in Ant's classpath, get the jar of <a href="../download.html">Apache Ivy</a> and edit the build.xml accordingly (see the comments at the begining of the file) + + * *__(optional)__* if Ivy is not in Ant's classpath, link:http://ant.apache.org/ivy/download.cgi[download the Ivy jar] and edit the `build.xml` accordingly (see the comments at the begining of the file) And that's it ! Now let's use it. @@ -70,20 +68,18 @@ ant build === Eclipse setup -You probably have already configured your project in Eclipse via the PDE. Let's see how to chnage that and use <a href="http://ant.apache.org/ivy/ivyde/";>Apache IvyDE</a>. - - +You probably have already configured your project in Eclipse via the PDE. Let's see how to change that and use link:http://ant.apache.org/ivy/ivyde/[Apache IvyDE]: -. so first remove from your project's classpath the PDE dependencies container; + + * First remove from your project's classpath the PDE dependencies container -. then right click on the ivy.xml you just added and select "Add Ivy library"; + + * then right click on the `ivy.xml` you just added and select "Add Ivy library" -. in the configuration panel of the IvyDE classpath container, as the settings file put '${workspace_loc:mypluginproject/ivysettings.xml}'; + + * in the configuration panel of the `IvyDE` classpath container, as the settings file put `${workspace_loc:mypluginproject/ivysettings.xml}` -. click finish and your Eclipse project should build now. + + * click finish and your Eclipse project should build now. -Nota Bene: to be resolved correctly Ivy is relying on the aggregated metadata of your target platform. Even if you want to only build with Eclipse, you will have to run the command `ant obrindex` at least one time. +NOTE: For resolution to work correctly, Ivy relies on the aggregated metadata of your target platform. Even if you want to only build with Eclipse, you will have to run the command `ant obrindex` at least one time. == Details on the setup @@ -95,8 +91,8 @@ Nota Bene: to be resolved correctly Ivy is relying on the aggregated metadata of When building an Eclipse plugin, we are relying on a "target platform", the Eclipse installation we want our plugin to be eventually installed into. For Ivy, this will represent the repository of artifacts. -Ivy needs an aggragation of the OSGi metadata in order to resolve a such repository. The Ant task <a href="../use/buildobr.html">buildobr</a> build a OBR (OSGi Bundle Repository) descriptor file from a set of OSGi bundles. So here we are using this Ant task to gather OSGi metadata from the Eclipse plugins in the "target platform". In the above exemple, the file is build in `target/repo-eclipse.xml`. +Ivy needs an aggragation of the OSGi metadata in order to resolve a such repository. The Ant task link:../use/buildobr.html[buildobr] builds a OBR (OSGi Bundle Repository) descriptor file from a set of OSGi bundles. So here we are using this Ant task to gather OSGi metadata from the Eclipse plugins in the "target platform". In the above example, the file is built in `target/repo-eclipse.xml`. -The plugin to be build has then a ivy.xml file describing its depedencies to be used by Ivy. Since the actual depedencies are in the MANIFEST.MF file, in the ivy.xml file we specify that it extends `META-INF/MANIFEST.MF`. So there not much dependencies specified in the ivy.xml. But as Ivy doesn't support the `Bundle-Fragment` OSGi feature, the ivy.xml can help specify the missing dependencies. +The plugin to be built has a `ivy.xml` file describing its depedencies to be used by Ivy. Since the actual depedencies are in the `MANIFEST.MF` file, in the `ivy.xml` file we specify that it extends `META-INF/MANIFEST.MF`. So there not much dependencies specified in the `ivy.xml`. But as Ivy doesn't support the `Bundle-Fragment` OSGi feature, the `ivy.xml` can help specify the missing dependencies. Having this setup, it is then a standard Ant+Ivy build. Ivy computes the classpath to be then used by the `javac` tasks. Note that `javac` is not aware of the OSGi metadata and is then incapable of failing to compile if private packages are accessed. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi/osgi-mapping.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/osgi-mapping.adoc b/asciidoc/osgi/osgi-mapping.adoc index daee184..5d8f06d 100644 --- a/asciidoc/osgi/osgi-mapping.adoc +++ b/asciidoc/osgi/osgi-mapping.adoc @@ -17,10 +17,11 @@ under the License. //// += OSGi mapping This page is a description of how OSGi™ dependencies are mapped into Apache Ivy™ ones -Goal: the purpose of this mapping is to transform an OSGi manifest into an ivy.xml, so Ivy can understand OSGi bundles and resolve them. We don't want to do the reverse here. +*Goal:* the purpose of this mapping is to transform an OSGi manifest into an ivy.xml, so Ivy can understand OSGi bundles and resolve them. We don't want to do the reverse here. == Bundle Symbolic name / Ivy organisation and module @@ -54,9 +55,9 @@ a| == Version and version range -The OSGi specification is defining a version as a composition of 3 numbers and an arbitrary qualifier. This fit well into the lazy definition of Ivy. We will just have to use a special latest strategy in Ivy. +The OSGi specification defines a version as a composition of 3 numbers and an arbitrary qualifier. This fits well into the lazy definition of Ivy. We will just have to use a special latest strategy in Ivy. -Then about version range, Ivy will understand correctly fully defined range as `[1.2.3,1.4.9)` or `(1.2.3,1.4.9]`. But for OSGi version range defined as in `1.2.3`, it has to be transformed into `[1.2.3,)` +When it comes to version ranges, Ivy will correctly understand fully defined range as `[1.2.3,1.4.9)` or `(1.2.3,1.4.9]`. But for OSGi version range defined as `1.2.3`, it has to be transformed into `[1.2.3,)` [] @@ -78,37 +79,35 @@ a| == Ivy configurations -The Ivy configuration is a notion that doesn't exist explicitely in OSGi, but some notion of the latter can be expressed with that configurations. +Ivy has the concept of link:../terminology.html#configurations[module configurations]. OSGi on the other hand, doesn't have such a concept. However, Ivy defines the following configurations, when it comes to dependency mapping for OSGi: -First the mapping is defining three configurations: + * `default` : it will contain every required dependency (transitively) -* `default` : it will contain every required dependency (transitively) + + * `optional` : it will contain every optional dependency and every required depedency the the first degree dependencies. -* `optional` : it will contain every optional dependency and every required depedency the the first degree dependencies. + + * `transitive-optional` : it will contain every optional dependency (optional transitively) -* `transitive-optional` : it will contain every optional dependency (optional transitively) + - -Then there will be some configurations used for the `use` parameter of the `Import-Package` OSGi manifest header. All of these kinds of configuration have their names starting with "use_". See in the next section. +Additionally, Ivy defines some more configurations while dealing with the `use` parameter of the `Import-Package` OSGi manifest header. All of these kinds of configuration have their names starting with `use_`. == OSGi capabilities -Generally speaking, declaring capabilities in an ivy.xml is useless (in the scope of this mapping which is to transform an OSGi manifest into an ivy.xml and not the reverse). In the resolve process we want to find the bundle which have the capability matching the expected requirement. In Ivy, if we are about to get the ivy.xml of a module, we are getting the bundle so we already have reached the requirement. +Generally speaking, declaring capabilities in an ivy.xml is useless (in the scope of this mapping which is to transform an OSGi manifest into an ivy.xml and not the reverse). In the resolve process we want to find the bundles which have the capability matching the expected requirement. In Ivy, if we are about to get the ivy.xml of a module, we are getting the bundle so we already have reached the requirement. -So OSGi capabilities of bundles in a repo will be gathered direclty from the manifests to passed directly to the Ivy resolver, no need to express them into ivy.xml, except for the Export-Package, see the next section. +So OSGi capabilities of bundles in a repo will be gathered directly from the manifests passed directly to the Ivy resolver, no need to express them into ivy.xml, except for the Export-Package, see the next section. === Export-Package -Exported package are declaring capabilities of the bundle in term of package. But they also declare dependencies between the declared package via the parameter `use`. These dependencies have to be declared in the ivy.xml. And we will use Ivy configurations for that. +Exported package, are declaring capabilities of the bundle in term of package. But they also declare dependencies between the declared package via the parameter `use`. These dependencies have to be declared in the ivy.xml. And we will use Ivy link:../terminology.html#configurations[module configurations] for that. -First, each exported package will be declared in the ivy.xml as a configuration. The name of the configuration will start will `use_` and will finished with the name of that package. +First, each exported package will be declared in the ivy.xml as a configuration. The name of the configuration will start will `use_` and will end with the name of that package. -Then each time an exported package is declared to use some other one, it will be mapped as a dependency between the Ivy configurations coresponding to those packages. +Then each time an exported package is declared to use some other one, it will be mapped as a dependency between the Ivy configurations corresponding to those packages. [] @@ -138,13 +137,13 @@ a| == OSGi Requirements / Ivy dependencies -In OSGi there are different kind of dependencies, which is an OSGi bundle repository documentation is called a "requirement". The problem is that Ivy is understanding only one kind of requirement, so we use here some extra attribute to declare those different kind of dependency. +In OSGi there are different kind of dependencies, which is an OSGi bundle repository documentation is called a "requirement". The problem is that Ivy undesrstands only one kind of requirement, so we use here some extra attribute to declare those different kind of dependency. === Require-Bundle -The OSGi `Require-Bundle` is some a requirement directly on a specific bundle. Ivy does it too. So we just use the `osgi="bundle"` extra attribute. +The OSGi `Require-Bundle` is a requirement directly on a specific bundle. To map that, Ivy will just use the `osgi="bundle"` link:../concept.html#extra[extra attribute]. If there is the OSGi `resolution` parameter specified to `optional`, then the dependency will be declared in the configuration `optional` and `transitive-optional`. Otherwise it will be declared in the `default` configuration. @@ -175,11 +174,11 @@ a| === Import-Package -The OSGi `Import-Package` is some a requirement on a package of a bundle. Ivy has no notion of package. So we will use the `osgi="pkg"` extra attribute. +The OSGi `Import-Package` is a requirement on a package of a bundle. Ivy has no notion of package. So we will use the `osgi="pkg"` link:../concept.html#extra[extra attribute]. If there is the OSGi `resolution` parameter specified to `optional`, then the dependency will be declared in the configuration `optional` and `transitive-optional`. Otherwise it will be declared in the `default` configuration. -As it is an import package the configuration of the dependency will be the `use_XXX` one. So that transitive dependency via the use parameter will be respected in the dependency. +As it is an import package, the configuration of the dependency will be the `use_XXX` one. This way, the transitive dependency via the `use` parameter will be respected in the dependency. [] @@ -208,7 +207,7 @@ a| == Execution environment -The OSGi `Bundle-RequiredExecutionEnvironment` manifest attribute is specifing is which environment the bundle is expected to run. In our problematic of dependency management it means that some of the transitive dependencies won't be resolved within the OSGi space but will be provided by the JRE. So we have to exclude from the dependency tree every requirement that will be provided by the environment. Basically it will be about excluding the packaged declared in the JRE. +The OSGi `Bundle-RequiredExecutionEnvironment` manifest attribute specifies which environment the bundle is expected to run. What that means in terms of dependency management is that some of the transitive dependencies won't be resolved within the OSGi space but will be provided by the JRE. While mapping this, Ivy will exclude from the dependency tree every requirement that will be provided by the environment. [] @@ -238,4 +237,4 @@ a| Ivy doesn't support the header `Fragment-Host`. -The work around is to manually specify as dependencies in the ivy.xml the bundles which would fit to be the extensions of the host bundle. +The workaround is to manually specify, as dependencies in the ivy.xml the bundles, which would fit to be the extensions of the host bundle. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi/sigil.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/sigil.adoc b/asciidoc/osgi/sigil.adoc index ea06ee3..5d78a6d 100644 --- a/asciidoc/osgi/sigil.adoc +++ b/asciidoc/osgi/sigil.adoc @@ -17,16 +17,17 @@ under the License. //// += Apache Felix Sigil -Another initiative to manage OSGi™ dependencies is the project link:http://felix.apache.org/site/apache-felix-sigil.html[Apache Felix Sigil™]. Sigil can used also together with Ivy. We will try to explain here the different approach taken there compared to the build-in OSGi capabilities of Ivy. +Another initiative to manage OSGi™ dependencies is the project link:https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Sigil[Apache Felix Sigil™]. Sigil can also be used together with Ivy. We will try to explain here the different approach taken there compared to the built-in OSGi capabilities of Ivy. == A different approach -Apache Felix Sigil is at its core about managing OSGi dependencies, not directly related to Ivy. Most of it core feature is about the implementation of the not yet released OBR (OSGi Bundle Repository) specification. It then provides integration layers with sevral tools so human being can actually use the OBR API. As "layer" there is an Eclipse plugin, and there are the Ant/Ivy tasks and resolver. +Apache Felix Sigil is at its core about managing OSGi dependencies, not directly related to Ivy. Most of it core feature is about the implementation of the not yet released OBR (OSGi Bundle Repository) specification. It then provides integration layers with several tools so that developers can use the OBR API. It provides an Eclipse plugin and there are the Ant/Ivy tasks and resolvers. -On the other hand the build in OSGi capabilities in Ivy are targeted against users already familiar with Ivy and their link:http://ant.apache.org/ivy/links.html[tools] like link:http://ant.apache.org/ivy/ivyde[Apache IvyDE™]. So with a minimum of effort, they can get OSGi dependency management. +On the other hand the built-in OSGi capabilities in Ivy are targeted towards users already familiar with Ivy and link:http://ant.apache.org/ivy/links.html[tools around it] like link:http://ant.apache.org/ivy/ivyde[Apache IvyDE™]. So with a minimum amount of effort, they can get OSGi dependency management. == Resulting differences @@ -36,19 +37,17 @@ On the other hand the build in OSGi capabilities in Ivy are targeted against use === Resolve -The build-in OSGi resolver is __obviously__ using the Ivy engine to do the resolution of the dependencies. The OSGi capability of Ivy is mainly implemented with a module descriptor parser which understands the OSGi metadata of a MANIFEST.MF. +The built-in OSGi resolver is __obviously__ using the Ivy engine to do the resolution of the dependencies. The OSGi capability of Ivy is mainly implemented with a module descriptor parser which understands the OSGi metadata of a `MANIFEST.MF`. On the other hand, Sigil is using a separate "engine" to do the resolution, the OBR, an engine which is dedicated to understand the OSGi metadata and their semantics. -The immediate consequence of this difference is that the build-in resolver is probably less accurate than the Sigil one as to understand the OSGi dependencies semantics. As explained in this link:osgi-mapping.html[page], the OSGi model doesn't fit well into the Ivy one. - -Whereas Ivy is not ready yet to fill most OSGi use cases, OSGi dependency management at build time is not that complex, contrary to the runtime one. We hope that Ivy will catch up soon. +The immediate consequence of this difference is that the built-in resolver is probably less accurate than the Sigil one when it comes to understanding the OSGi dependencies semantics. As explained in this link:osgi-mapping.html[page], the OSGi model doesn't fit well into the Ivy one. === Source of metadata -Apache Felix Sigil has its own format about specifying the OSGi dependencies. Whereas Ivy requires an ivysettings.xml and an ivy.xml, Sigil requires a sigil-repos.properties and a sigil.properties. Then if you want to use the Sigil resolver in Ivy, you will need 4 files, the 2 Ivy ones and the 2 Sigil ones, as described link:http://felix.apache.org/site/apache-felix-sigil-ivy-quickstart.html[there]. +Apache Felix Sigil has its own format about specifying the OSGi dependencies. Whereas Ivy requires an `ivysettings.xml` and an `ivy.xml`, Sigil requires a `sigil-repos.properties` and a `sigil.properties`. Then if you want to use the Sigil resolver in Ivy, you will need 4 files, the 2 Ivy ones and the 2 Sigil ones, as described in the Sigil quickstart link:https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Sigil+Ivy+Quickstart[here]. -To support OSGi directly in Ivy, you just need to add an extra namespace in the ivy.xml, and in the ivysettings.xml, just declare the proper resolver and latest revision strategy. +To support OSGi directly in Ivy, you just need to add an extra namespace in the `ivy.xml`, and in the `ivysettings.xml` just declare the proper resolver and latest revision strategy. http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi/standard-osgi.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/standard-osgi.adoc b/asciidoc/osgi/standard-osgi.adoc index a23381c..ccbc67e 100644 --- a/asciidoc/osgi/standard-osgi.adoc +++ b/asciidoc/osgi/standard-osgi.adoc @@ -17,15 +17,15 @@ under the License. //// - += Building a standard OSGi bundle [NOTE] ==== Note that this feature is considered as *experimental*. -It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. -==== +It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discuss your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found, on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. +==== ''' @@ -37,7 +37,7 @@ It should work with simple configuration but may not in complex ones. If you hav This page describes how to build an OSGi™ bundle with Apache Ivy™. In this use case, we just basically want to compute a classpath to compile, optionaly one for testing too, and then publish our bundle in a OSGi aware repository. -In oder to produce OSGi metadata of suffient quality and to avoid maintaining them manually, the link:http://www.aqute.biz/Code/Bnd[bnd] tool will be used. The approach taken is then an "Ivy file first" approach. The dependencies will be specified in the ivy.xml file, the MANIFEST.MF being generated from the computed classpath. +In oder to produce OSGi metadata of sufficient quality and to avoid maintaining them manually, the link:http://bndtools.org/[bnd] tool will be used. The approach taken is then an "Ivy file first" approach. The dependencies will be specified in the `ivy.xml` file, the `MANIFEST.MF` being generated from the computed classpath. @@ -45,10 +45,17 @@ In oder to produce OSGi metadata of suffient quality and to avoid maintaining th In few steps, we will setup a build to compile and publish an OSGi bundle. -. download this link:../samples/standard-osgi/ivy.xml[ivy.xml], this link:../samples/standard-osgi/ivysettings.xml[ivysettings.xml], this link:../samples/standard-osgi/build.xml[build.xml], this link:../samples/standard-osgi/org.apache.ivy.sample.standard-osgi.bnd[bnd file], and put them into your project folder; + + * download this link:../samples/standard-osgi/ivy.xml[ivy.xml], this link:../samples/standard-osgi/ivysettings.xml[ivysettings.xml], this link:../samples/standard-osgi/build.xml[build.xml], this link:../samples/standard-osgi/org.apache.ivy.sample.standard-osgi.bnd[bnd file], and put them into your project folder + + * in the `ivysettings.properties`, specify the location of the plugins folder of your Eclipse target + + * *__(optional)__* by default the `build.xml` is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case -. in the ivysettings.properties, specify the location of the plugins folder of your Eclipse target; + + * *__(optional)__* if Ivy is not in Ant's classpath, link:http://ant.apache.org/ivy/download.cgi[download the Ivy jar] and edit the `build.xml` accordingly (see the comments at the begining of the file) -. __(optional)__ by default the build.xml is expecting the sources to be in the `src` folder. You may want to edit it if it is not the case + +To build the project, run: -. __(optional)__ if Ivy is not in Ant's classpath, get the jar of link:../download.html[Apache Ivy] and edit the build.xml accordingly (see the comments at the begining of the file) + +[source] +---- +ant build +---- http://git-wip-us.apache.org/repos/asf/ant-ivy/blob/fcc90377/asciidoc/osgi/target-platform.adoc ---------------------------------------------------------------------- diff --git a/asciidoc/osgi/target-platform.adoc b/asciidoc/osgi/target-platform.adoc index d88aa55..ca884ce 100644 --- a/asciidoc/osgi/target-platform.adoc +++ b/asciidoc/osgi/target-platform.adoc @@ -17,19 +17,20 @@ under the License. //// - += Managing a target platform [NOTE] ==== Note that this feature is considered as *experimental*. -It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discussed your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. +It should work with simple configuration but may not in complex ones. If you have any issue with that feature, you are welcomed to come discuss your use case on the link:http://ant.apache.org/ivy/mailing-lists.html[ivy-user] mailing list, or discuss about implementation issues or improvement you may have found, on link:http://ant.apache.org/ivy/mailing-lists.html[ant-dev]. + ==== -The concept of "target platform" is a concept introduced by Eclipse™ to describe the set of bundle which will run together in an OSGi™ environement. Then when developping an OSGi bundle, we expect it to run in a such "target platform". +The concept of "target platform" is a concept introduced by Eclipse™ to describe the set of bundles which will run together in an OSGi™ environement. Then when developping an OSGi bundle, we expect it to run in such a "target platform". -When developping a single OSGi bundle, a single ivy.xml (together with the use of the link:../use/fixdeps.html[fixdeps] task) is sufficent to describe precisely how the bundle requirements. +When developping a single OSGi bundle, a single `ivy.xml` (together with the use of the link:../use/fixdeps.html[fixdeps] task) is sufficent to describe precisely the bundle requirements. But when developping several bundles, it will be error prone to declare for each bundle its dependencies. Because once deployed in an OSGi environement, the bindings are sensitive to the available bundles. So when developping, we must ensure that the set of bundles will be the same set as the one at deploy time. @@ -42,20 +43,21 @@ The concept of "target platform" is a perfect fit to describe the set of bundles First you need a project (basically a folder) in which you will manage your target platform. In this project you'll need 3 files: -* an link:../samples/target-platform/ivy.xml[ivy.xml] in which you will describe the bundles you need, + + * an link:../samples/target-platform/ivy.xml[ivy.xml] in which you will describe the bundles you need + + * an link:../samples/target-platform/ivysettings.xml[ivysettings.xml] which will describe where to download bundles from -* an link:../samples/target-platform/ivysettings.xml[ivysettings.xml] which will describe where to download bundles from, + + * and a link:../samples/target-platform/build.xml[build.xml] with which you'll manage your target platform -* and a link:../samples/target-platform/build.xml[build.xml] with which you'll manage your target platform. + +In the build there is a target: `update-dependencies`. This target will do a resolve with the `ivy.xml` and will generate an `ivy-fixed.xml` from the resolved depedencies. This `ivy-fixed.xml` file contains only fixed non transitive dependencies (see the link:../use/fixdeps.html[fixdeps] task for further info). With that `ivy-fixed.xml` file, subsequent dependency resolutions are then reproducible and will always generate the same set of artifacts. -In the build there is a first important target: `'update-dependencies'`. Since the OSGi dependencies are very sensible to the available resources to resolve against, it is important to make the resolve as tight and reproductible as possible. First this target will do a resolve with the `ivy.xml`: a resolve which is very sensible to the content of the remote repo, thus not much reproductible. And it is will generate an `ivy-fixed.xml` from the resolved depedencies: this Ivy file contains only fixed non transitive dependencies (see the link:../use/fixdeps.html[fixdeps] task for further info). With that `ivy-fixed.xml` file, resolves are then reproductible and will always generate the same set of artifacts. +Once generated, it is recommended to share that `ivy-fixed.xml` file into you version control system (subversion, git, etc...). The target `update-dependencies` is then to be launched each time you edit the `ivy.xml`, when you want to change the content of your target platform. -Once generated, it is recommended to share that `ivy-fixed.xml` file into you version control system (subversion, git, etc...). The target `'update-dependencies'` is then to be launched each time you edit the `ivy.xml`, when you want to change the content of your target platform. +The second target `generate-target-platform` will generate an `obr.xml`, a OSGi Bundle repository descriptor. This file will list every artifact wich has been resolved by the `ivy-fixed.xml`. Then each of your bundles you develop will do its resolve against that `obr.xml` (see the link:../resolver/obr.html[obr resolver]). -The second target `'generate-target-platform'` will generate an `obr.xml`, a OSGi Bundle repository descriptor. This file will list every artifact wich has been resolved by the `ivy-fixed.xml`. Then each of your bundles you develop will do its resolve against that `obr.xml` (see the link:../resolver/obr.html[obr resolver]). +The generated `obr.xml` contains paths to the local filesystem, so it is neither recommended to share it between developers nor commit it to version control system. -The generated `obr.xml` contains paths to the local filesystem, so it is recommended to not share it between developpers. +If it is required to develop your plugin with the Eclipse PDE plugin, you can then use the alternative target `generate-retrieved-target-platform`. It has the same principle as the `generate-target-platform` but the artifacts are also retrieved in a single folder, just like the plugins in an Eclipse install. That way you can define your target platform within Eclipse quite easily. -If it is required to develop your plugin with the Eclipse PDE plugin, you can then use the alternative target `generate-retrieved-target-platform`. It has the same principle than the `'generate-target-platform'` but the artifacts are also retrieved in a single folder, just like are plugins in an Eclipse install. That way you can define your target platform within Eclipse quite easily.
