Wiki source code of Building and Deploying your Extension
Last modified by Vincent Massol on 2020/01/28 14:36
Show last authors
author | version | line-number | content |
---|---|---|---|
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]]. |