Last modified by Vincent Massol on 2020/01/28 14:36

Show last authors
1 {{error}}
2 In progress
3 {{/error}}
4
5 {{box cssClass="floatinginfobox" title="**Contents**"}}
6 {{toc/}}
7 {{/box}}
8
9 If you're developing an Extension to XWiki (see [[XWiki Architecture>>platform:DevGuide.Architecture]]), you may want to save your sources under an SCM and use a build tool to transform its source into a form that can be executed inside XWiki. [[XWiki itself provides a Maven build>>dev:Community.Building]] and it's likely that you'll also want to use [[Maven>>https://maven.apache.org/]] to build your own Extension. This tutorial explains how to create such a build for your Extension.
10
11 Note that there are various tutorials in the [[Dev Guide>>platform:DevGuide.WebHome]] for developing Extensions to XWiki: Java Macros, Wiki Macros, Java Components, Skin Extensions, etc. Refer to those to develop your Extension.
12
13 Your Extension falls in one of the 2 categories:
14
15 * Extensions that are written in Java and packaged as JAR files
16 * Extensions that are written in wiki pages and packaged as XAR files
17
18 = Choosing Versions =
19
20 Your Extension will need to depend on some XWiki modules (a.k.a Artifacts in Maven terminology), refer to the development tutorial for choosing which one are needed. However you'll also need to pick an XWiki version of those modules. Luckily, the XWiki Development Team releases all the core modules together under a single version number which corresponds to the XWiki version you see when you [[download XWiki>>enterprise:Main.Download]].
21
22 You should know that the version you pick will have one important consequence: only versions of XWiki greater than the version you pick will be able to install your Extension. As a consequence **we recommend that your Extension depend on the latest LTS version of XWiki (or older)**. This is the best way to ensure that the maximum number of XWiki users will be able to use your Extension while at the same time not having to support too old versions of XWiki.
23
24 == Parent POM Version ==
25
26 In order to make your build simpler to write, we recommend that your ##pom.xml## depend on the {{scm project="xwiki-commons" path="xwiki-commons-pom/pom.xml"}}##org.xwiki.commons:xwiki-commons-pom##{{/scm}} POM artifact, using the version of XWiki that you have chosen (see above).
27
28 Of course by doing so, you'll inherit all the best practices used by the XWiki Development Team to develop XWiki itself but that's usually a good thing :)
29
30 One consequence though is that you'll inherit the version of Java defined for the Maven Compiler plugin:
31
32 * Java 6 for XWiki 6.x
33 * Java 7 for XWiki 7.x
34
35 Of course you can override this to use a more recent version of Java in your ##pom.xml## (by configuring the Maven Compiler plugin) but bear in mind that if you do, all the users who are using XWiki will not be able to use your Extension since it'll require a version of Java greater than the minimal requirement for that XWiki version. For example if you build with Java 8 and you depend on XWiki 7.x then your extension will not work for users who are running XWiki under Java 7.
36
37 Beware that by depending on ##org.xwiki.commons:xwiki-commons-pom## you'll inherit several configurations that you'll probably wish to override:
38
39 * The XWiki project's URL: ##<url>## tag
40 * The XWiki project's groupId: ##<groupId>## tag
41 * The XWiki projet's version: ##<version>## tag
42 * The XWiki project's developers: ##<developers>## tag
43 * The XWiki project's license: ##<licenses>## tag
44 * The XWiki project's issue management tool: ##<issueManagement>##
45 * The XWiki project's mailing lists: ##<mailingLists>##
46 * The XWiki project's organization: ##<orgnization>##
47 * The XWiki project's SCM location: ##<scm>##
48 * etc.
49
50 You should also know that the Maven property ##commons.version## will be defined and you can use it for your XWiki dependencies. We recommend to define a Maven property named ##xwiki.version## and use it as follows:
51
52 {{code language="xml"}}
53 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
54 <modelVersion>4.0.0</modelVersion>
55 ...
56 <properties>
57 ...
58 <xwiki.version>${commons.version}</xwiki.version>
59 </properties>
60 ...
61 <dependencies>
62 ...
63 <dependency>
64 <groupId>org.xwiki.commons</groupId>
65 <artifactId>xwiki-commons-component-api</artifactId>
66 <version>${xwiki.version}</version>
67 </dependency>
68 <dependency>
69 <groupId>org.xwiki.platform</groupId>
70 <artifactId>xwiki-platform-oldcore</artifactId>
71 <version>${xwiki.version}</version>
72 </dependency>
73 ...
74 </dependencies>
75 ...
76 {{/code}}
77
78 If you wish to not depend on ##org.xwiki.commons:xwiki-commons-pom## you could take inspiration from the [[Parent POM example for XWiki Contrib projects>>https://github.com/xwiki-contrib/parent]].
79
80 = POM Format =
81
82 The POM format is that of a typical Maven project with the addition of XWiki-specific custom Maven properties used to hold Metadata for your Extension.
83
84 If you wish that your Extension be installable with the [[XWiki Distribution Wizard>>platform:Features.DistributionWizard]] or the [[XWiki Extension Manager>>extensions:Extension.Extension Manager Application]] (the Distribution Wizard uses the Extension Manager behind the hood), you'll need to provide the following additional metadata:
85
86 * Your Extension's name: You can provide it either in the Maven ##<name>## tag or through a Maven property named ##xwiki.extension.name##. If the later is defined, it's the one that will be used. This allows to provide a different name for the Maven build and for your Extension when installed.
87 * (optional) Your Extension's Category, using the Maven property named ##<xwiki.extension.category>##. Valid values are [[listed here>>extensions:Extension.Repository Application||anchor="HCategories"]]. This is used to Categorize your Extension in the Extension Manager's UI.
88 * (optional) Extension relocation data. If you've modified the ##groupId## or ##artifactId## of your Extension you need to tell it to the Extension Manager so that it can handle upgrades and understand it's the same extension being upgraded. This is achieved by using the ##xwiki.extension.features## Maven property. For example if you previously had an Extension id of ##my-old-group-id:my-old-artifact-id## and you're now using another id, you'd use:(((
89 {{code language="xml"}}
90 <properties>
91 ...
92 <!-- Old names of this module used for retro compatibility when resolving dependencies of old extensions -->
93 <xwiki.extension.features>my-old-group-id:my-old-artifact-id</xwiki.extension.features>
94 ...
95 </properties>
96 {{/code}}
97 )))
98
99 Note that the Extension Manager will also read the following standard Maven POM elements:
100
101 * ##<groupId>## and ##<artifactId>##: used as your Extension's id (FYI, the format is ##<groupId>:<artifactId>##)
102 * ##<description>##: used as your Extension's description
103 * ##<developers>##: used as your Extension's developers
104 * ##<name>##: used as your Extension's name if no ##xwiki.extension.name## property is defined
105
106 {{info}}
107 If you're interested by details, the XWiki Extension Manager gets information about your Extension by extracting it from either your JAR or your XAR (depending on whether your extension is written in Java or in wiki pages), as follows:
108 * For JARs: the Maven POM that is packaged in ##META-INF/maven/*## and the Extension Manager parses it. However since the Maven POM format doesn't contain all the information XWiki requires, XWiki defines some additional custom Maven properties.
109 * For XARs: the Maven XAR plugin that XWiki provides to build a XAR generates a file in your XAR named ##package.xml## which contains all the required metadata.
110 {{/info}}
111
112 Example POM using XWiki's 6.4.6 LTS version as of this writing (adapt to the latest LTS):
113
114 {{code language="xml"}}
115 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
116 <modelVersion>4.0.0</modelVersion>
117 <parent>
118 <groupId>org.xwiki.commons</groupId>
119 <artifactId>xwiki-commons-pom</artifactId>
120 <version>6.4.6</version>
121 </parent>
122 <groupId>... your group id...</groupId>
123 <artifactId>... your artifact id...</artifactId>
124 <version>... your SNAPSHOT version, e.g. 1.0-SNAPSHOT...</version>
125 <name>... your name...</name>
126 <description>... your description...</description>
127 <scm>
128 <connection>... your read-only SCM id...</connection>
129 <developerConnection>... your writeable SCM id...</developerConnection>
130 <url>... your view URL for your SCM...</url>
131 </scm>
132 <developers>
133 <developer>
134 <id>...scm id of developer 1...</id>
135 <name>... full Name of developer 1...</name>
136 </developer>
137 ...
138 <developer>
139 <id>...scm id of developer N...</id>
140 <name>... full Name of developer N...</name>
141 </developer>
142 </developers>
143 <properties>
144 <!-- The Extension name. If not defined, the <name> property is used -->
145 <xwiki.extension.name>... your extension's name...</xwiki.extension.name>
146 <!-- The extension's category -->
147 <xwiki.extension.category>... your extension's category...</xwiki.extension.category>
148 </properties>
149 <dependencies>
150 ... dependencies required by your Extension ...
151 </dependencies>
152 ... other standard Maven POM configuration here (plugin configurations, etc) ...
153 </project>
154 {{/code}}
155
156 == For a Java-based Extension ==
157
158 In addition to the format defined above you'll need to specify the JAR ##<packaging>## as in:
159
160 {{code language="xml"}}
161 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
162 ...
163 <packaging>jar</packaging>
164 ...
165 {{/code}}
166
167 == For a Wiki-based Extension ==
168
169 In addition to the format defined above you'll need to specify the XAR ##<packaging>##. You'll also need to register the XWiki XAR lifecycle to Maven and specify the version of the XAR plugin to use, as in:
170
171 {{code language="xml"}}
172 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
173 ...
174 <packaging>xar</packaging>
175 ...
176 <build>
177 <!-- Needed to add support for the XAR packaging -->
178 <extensions>
179 <extension>
180 <groupId>org.xwiki.commons</groupId>
181 <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
182 <version>${xwiki.version}</version>
183 </extension>
184 </extensions>
185 <plugins>
186 <!-- The XAR packaging uses the XAR plugin and thus we need to define what version to use -->
187 <plugin>
188 <groupId>org.xwiki.commons</groupId>
189 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
190 <version>${xwiki.version}</version>
191 </plugin>
192 ...
193 </plugins>
194 ...
195 </build>
196 ...
197 {{/code}}
198
199 = Building your Extension =
200
201 Make sure that you've [[configured Maven to use XWiki's Remote Repository>>dev:Community.Building||anchor="HInstallingMaven"]] as otherwise Maven will not find your declared XWiki dependencies.
202
203 To build your Extension, execute ##mvn clean install##
204
205 If your Extension is a XAR one, you can also run ##mvn xar:format## to let the [[Maven XAR plugin>>dev:Community.XARPlugin||anchor="HFormatMojo"]] perform some formatting on the XML files representing your wiki pages.
206
207 = Deploying your Extension =
208
209 Now that you've built your Extension you have a XAR or JAR and you need to install it inside XWiki. You have several options for doing so.
210
211 == As a Core Extension ==
212
213 If your Extension is a JAR you can deploy it by copying it to your Servlet container's ##WEB-INF/lib## directory along with all its dependencies (excluding the XWiki dependencies that are already present in ##WEB-INF/lib##). This is not the easiest way and you'll need to restart XWiki for the Extension to be loaded. Your Extension will be recognized as a Core Extension by the Extension Manager and as a consequence it'll be available globally for all the subwikis in your XWiki instance.
214
215 == As a XAR Import ==
216
217 If your Extension is a XAR you can go to the Wiki Administration UI and [[Import it>>platform:AdminGuide.ImportExport]]. The XWiki Importer will recognize that its an Extension (through the generated ##package.xml## file, see above) and will install it as an Extension available for all the subwikis in your XWiki instance.
218
219 == Using a Local Extension Repository ==
220
221 After you've built your Extension using Maven, the generated artifact is available in your local Maven Repository and you could configure your XWiki instance to recognize this local Maven Repository as an Extension Repository. To do this, edit XWiki's ##WEB-INF/xwiki.properties## file and uncomment the following lines (the first line is the important one but since you're overriding the default configuration you'll also need to have the following 2 lines which are the default you get when you don't configure repositories explicitly):
222
223 {{code}}
224 extension.repositories=local:maven:file://${sys:user.home}/.m2/repository
225 extension.repositories=maven-xwiki:maven:http://nexus.xwiki.org/nexus/content/groups/public
226 extension.repositories=extensions.xwiki.org:xwiki:http://extensions.xwiki.org/xwiki/rest/
227 {{/code}}
228
229 Once this is done you can install your Extension through the [[Extension Manager's UI by clicking "Advanced Search">>extensions:Extension.Extension Manager Application||anchor="HAdvancedSearch"]] and entering your Extension's id and version. Note that the reason you cannot using the Search feature of the Extension Manager is because a Maven Repository is not a searchable Extension repository (Maven doesn't offer a search feature by default).
230
231 == Using extensions.xwiki.org ==
232
233 Last but not least, you could deploy your Extension on the [[xwiki.org Extensions wiki>>extensions:Main.WebHome]] so that it's available by default to everyone in the world using XWiki! If your extension is not meant to be private this is obviously the recommended approach.
234
235 To do so, register on [[xwiki.org>>http://xwiki.org]] and Contribute an extension on [[extensions.xwiki.org>>extensions:Main.WebHome]].
236
237 Note that you also have the possibility to share your extension with the rest of the XWiki community by making it a [[XWiki Contrib project>>contrib:Main.WebHome]]. If you do so, the XWiki project offers a streamlined solution for deploying easily your extension onto extensions.xwiki.org (in addition to offering several other tools, such as an issue tracker, a CI, and more).
238
239 = Need Help? =
240
241 If you still need help writing and deploying your XWiki Extension, contact the [[XWiki Support>>xwiki:Main.Support]].

Get Connected