Hide last authors
Manuel Smeria 73.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
VincentMassol 1.1 4
Vincent Massol 125.1 5 = Build Requirements =
6
Vincent Massol 130.1 7 * See [[Java support>>Community.SupportStrategy.JavaSupportStrategy.WebHome||anchor="HByXWikiVersions"]] to find which version to build XWiki with
8 ** e.g. Use Java 8 for XWiki < 14.0 and Java 11 for XWiki >= 14.0
Thomas Mortagne 131.1 9 * Make sure you install a Maven version >= 3.6.3. Note that our [[CI>>https://ci.xwiki.org]] builds XWiki using Maven 3.8.3 and thus this is our recommended version.
Vincent Massol 111.1 10 * Windows users have several choices for getting past the [[long paths issue>>https://github.com/msysgit/git/pull/122]] (255 char limitation on Windows) and building XWiki:
11 ** Use either [[GitHub Desktop>>https://desktop.github.com/]] or [[Git for Windows>>https://git-for-windows.github.io/]] and set ##core.longpaths## to ##True##: {{code}}git config --global core.longpaths true{{/code}}.
12 ** Use [[Cygwin>>https://www.cygwin.com/]] which works out of the box.
Vincent Massol 111.3 13 * If you're using openJDK, you must use a [[version equal or newer than 8u191-b12>>https://stackoverflow.com/questions/53010200/maven-surefire-could-not-find-forkedbooter-class/53016532#53016532]].
Vincent Massol 125.1 14 * To run functional tests you need to have [[Docker installed>>https://docs.docker.com/get-docker/]].
15 ** We still have functional tests that have not yet been moved to Docker-based tests and for those you need to have FireFox installed locally. See the [[official Docker build image to check the required FF version>>https://github.com/xwiki/xwiki-docker-build/blob/master/build/Dockerfile#L52]].
Vincent Massol 46.2 16
Vincent Massol 40.1 17 = Understanding the directory structure =
VincentMassol 1.5 18
Vincent Massol 128.2 19 Before you start it's good to have some minimal understanding of [[how Maven works>>https://maven.apache.org/users/index.html]]. You probably won't need it if everything goes fine but you'll need that knowledge if something breaks! ;-)
VincentMassol 1.2 20
Vincent Massol 60.1 21 The first thing to understand is the [[directory structure we use>>SourceRepository]].
VincentMassol 1.2 22
Vincent Massol 40.1 23 = Checking out the sources =
VincentMassol 1.6 24
Vincent Massol 60.1 25 Use your favorite SCM client to [[check out the Project>>SourceRepository]] you wish to build.
VincentMassol 1.6 26
Vincent Massol 40.1 27 = Installing Maven =
VincentMassol 1.4 28
Thomas Mortagne 128.1 29 * Install [[Maven 3.5.4 or greater>>https://maven.apache.org/]]. Create an ##M2_HOME## environment variable pointing to where you have installed Maven. Add ##M2_HOME/bin## to your PATH environment variable.(((
Manuel Smeria 73.2 30 {{info}}
Thomas Mortagne 128.1 31 For more information on how to install Maven or how to use it check this [[excellent Maven book>>https://www.sonatype.com/books/mvnref-book/reference/]].
Manuel Smeria 73.2 32 {{/info}}
Vincent Massol 40.1 33 )))
Vincent Massol 82.1 34 * Make sure you give Maven's JVM enough memory. XWiki's build uses Aspects and GWT compilers which need lots of memory. A good value is to give the JVM 1024MB. To do that set an environment variable named ##MAVEN_OPTS##. For example on Unix add the following to your shell startup script (depending on your shell you might need to prefix the variable with ##export##):(((
Manuel Smeria 73.2 35 {{code language="none"}}
Vincent Massol 124.1 36 MAVEN_OPTS="-Xmx1024m"
Manuel Smeria 73.2 37 {{/code}}
Vincent Massol 124.1 38
39 Note that XWiki's tests are executed in a separate JVM which requires 1024MB of memory. Thus, in total, you need to have 2GB of free RAM to build XWiki.
Thomas Mortagne 81.1 40 )))
Vincent Massol 85.1 41 * Create a ##~~/.m2/settings.xml## file with the XWiki custom remote repository defined as shown below (if you're using a Repository Manager such as Nexus or Artifactory, you should add the XWiki Maven Remote repositories in there instead). If you are on Windows, create the directory ##.m2## in your home directory, e.g. ##C:\Documents and Settings\Administrator\.m2##. If you cannot do this from Windows Explorer, open a command line and use ##md .m2##.(((
42 {{info}}
43 You might be wondering why we don't push all XWiki artifacts to Maven Central and thus remove the need to declare the XWiki Maven Repositories.
44
45 Actually we do this for XWiki Commons and XWiki Rendering. Since these 2 projects contain libraries that are independent of the concept of wikis, this makes it very easy for everyone to use them in their own projects.
46
Vincent Massol 128.3 47 We haven't done so for XWiki Platform this far because Maven Central imposes a requirement that we cannot fulfil at the moment: all artifacts deployed there must not have dependencies on other artifacts that are not present on Maven Central. And we do have a lot of such 3rd party dependencies. Some of them do not even exist in any Maven Repository and we put them in our [[XWiki Externals Repository>>https://maven.xwiki.org/externals/]].
Vincent Massol 85.1 48
49 Note that we recommend using a Maven Repository Manager to make it easier to maintain your Maven Repositories setup.
50 {{/info}}
51
Vincent Massol 39.1 52 {{code language="xml"}}
VincentMassol 1.30 53 <settings>
54 <profiles>
55 <profile>
56 <id>xwiki</id>
57 <repositories>
58 <repository>
Thomas Mortagne 53.1 59 <id>xwiki-snapshots</id>
60 <name>XWiki Nexus Snapshot Repository Proxy</name>
Thomas Mortagne 128.1 61 <url>https://nexus.xwiki.org/nexus/content/groups/public-snapshots</url>
Thomas Mortagne 53.1 62 <releases>
63 <enabled>false</enabled>
64 </releases>
65 <snapshots>
66 <enabled>true</enabled>
67 </snapshots>
68 </repository>
69 <repository>
Vincent Massol 52.1 70 <id>xwiki-releases</id>
71 <name>XWiki Nexus Releases Repository Proxy</name>
Thomas Mortagne 128.1 72 <url>https://nexus.xwiki.org/nexus/content/groups/public</url>
Vincent Massol 52.1 73 <releases>
74 <enabled>true</enabled>
75 </releases>
76 <snapshots>
77 <enabled>false</enabled>
78 </snapshots>
79 </repository>
Thomas Mortagne 53.1 80 </repositories>
81 <pluginRepositories>
82 <pluginRepository>
Thomas Mortagne 98.1 83 <id>xwiki-snapshots</id>
Thomas Mortagne 53.1 84 <name>XWiki Nexus Plugin Snapshot Repository Proxy</name>
Thomas Mortagne 128.1 85 <url>https://nexus.xwiki.org/nexus/content/groups/public-snapshots</url>
Vincent Massol 52.1 86 <releases>
87 <enabled>false</enabled>
88 </releases>
89 <snapshots>
90 <enabled>true</enabled>
91 </snapshots>
Thomas Mortagne 53.1 92 </pluginRepository>
Vincent Massol 52.1 93 <pluginRepository>
Thomas Mortagne 98.1 94 <id>xwiki-releases</id>
Vincent Massol 52.1 95 <name>XWiki Nexus Plugin Releases Repository Proxy</name>
Thomas Mortagne 128.1 96 <url>https://nexus.xwiki.org/nexus/content/groups/public</url>
Vincent Massol 52.1 97 <releases>
98 <enabled>true</enabled>
99 </releases>
100 <snapshots>
101 <enabled>false</enabled>
102 </snapshots>
103 </pluginRepository>
104 </pluginRepositories>
105 </profile>
106 </profiles>
107 <activeProfiles>
108 <activeProfile>xwiki</activeProfile>
109 </activeProfiles>
110 </settings>
111 {{/code}}
112
Manuel Smeria 73.2 113 {{info}}
Thomas Mortagne 128.1 114 Depending on your geographical location, you should use closer Maven repositories to speed up your build process. For more information refer to the [[Maven Mirror Settings Guide>>https://maven.apache.org/guides/mini/guide-mirror-settings.html]].
Thomas Mortagne 81.1 115 {{/info}}
Vincent Massol 40.1 116 )))
rssh 9.1 117
Vincent Massol 40.1 118 = Building with Maven =
Sergiu Dumitriu 34.2 119
Vincent Massol 96.4 120 Now that you have installed Maven and checked out the [[Projects>>SourceRepository#HTopLevelProjects]] you wanted to work on, you'll want to build them or parts of them. A project is made of modules. To build a module in Maven just issue the command:
Vincent Massol 31.1 121
Vincent Massol 60.2 122 {{code}}
123 mvn clean install
124 {{/code}}
125
Vincent Massol 128.2 126 Thanks to XWiki's [[Continuous Integration setup>>DevelopmentPractices#HContinuousIntegration]] you can check out and build any single module (and its children) you wish without having to rebuild the other modules from source. Maven will pick the latest version of your module's dependencies from [[XWiki's Maven remote repositories>>https://maven.xwiki.org/]]. Of course if you have uncommitted changes in a dependent module, you'll want to build that module before. The build result is placed in two places:
Manuel Smeria 73.2 127
Vincent Massol 128.2 128 * Your [[local maven repository>>https://maven.apache.org/guides/introduction/introduction-to-repositories.html]], for making the module available to other projects or modules using maven (even other XWiki modules take the needed libraries from this repository, and not directly from a "neighbor" directory)
Vincent Massol 60.1 129 * In a subdirectory of that module, called ##target##.
Vincent Massol 31.1 130
Vincent Massol 60.1 131 {{info}}
Manuel Smeria 73.2 132 Some of the modules built by XWiki are very large (in the 40MB+ size) and sometimes you don't absolutely need the latest version to get downloaded as it'll take too long. In that case here's a tip: run Maven in 'no-snapshot-update' mode with ##mvn install -nsu##.
Vincent Massol 60.1 133 {{/info}}
Vincent Massol 31.1 134
Vincent Massol 60.1 135 {{warning}}
Vincent Massol 83.2 136 You might encounter a ##java.lang.OutOfMemoryError## error during ##aspectj:compile##. You must increase the maximum memory used by maven, by setting ##MAVEN_OPTS=-Xmx1024m## (or a larger amount of memory if needed).
Vincent Massol 60.1 137 {{/warning}}
Vincent Massol 38.1 138
Vincent Massol 60.1 139 == Using Profiles ==
VincentMassol 1.56 140
Vincent Massol 128.2 141 Project builds define several [[Maven Profiles>>https://maven.apache.org/guides/introduction/introduction-to-profiles.html]]. We've standardized their names across Projects.
Vincent Massol 39.1 142
Vincent Massol 60.1 143 Here are the most common ones:
Manuel Smeria 73.2 144
145 * ##legacy##: Includes the [[legacy modules>>DevelopmentPractices#HDeprecationRules]] in the build.
Vincent Massol 60.1 146 * ##integration-tests##: Executes integration and functional tests in the build.
Vincent Massol 110.1 147 ** ##docker##: Executes integration tests that are Docker-based. You'll need to have Docker installed for this to work.
Vincent Massol 60.1 148 * ##jetty##, ##glassfish##: Run the build for the specified container (##jetty## is the default when not specified).
Thomas Mortagne 81.1 149 * ##hsqldb## (Hypersonic SQL), ##mysql## (MySQL), ##pgsql## (PostgreSQL), ##derby## (Derby): Run the build for the specified database (##hsqldb## is the default when not specified).(((
Vincent Massol 60.1 150 {{warning}}
151 Hypersonic and Derby are embedded database so you won't need anything setup to execute the build for them. However for MySQL and PostgreSQL you'll need to have the database installed, set up and running before you can run the build with their profiles.
Vincent Massol 39.1 152 {{/warning}}
Vincent Massol 60.1 153 )))
154 * ##firefox## (Firefox), ##iexplore## (Internet Explorer), ##chrome## (Google Chrome), ##otherbrowser## (need to define ##browserPath## property to use that one): Run the functional tests on the specified browser (##firefox## is the default when not specified).
155 * ##dev##: only build wysiwyg for English/Firefox. Very useful to speed up the build of XWiki Platform
Thomas Mortagne 97.1 156 * ##distribution##: {{info}}Since 9.5RC1{{/info}} Also build distribution packages (the WAR, the flavor, the jetty/hsqldb package, etc)
Vincent Massol 110.1 157 ** ##flavor-integration-tests##: {{info}}Since 9.5RC1{{/info}} Execute integration and functional tests related to the the default flavor located in ##xwiki-platform##.
VincentMassol 1.60 158
Vincent Massol 60.1 159 More "exotic" ones:
Manuel Smeria 73.2 160
Vincent Massol 128.2 161 * ##release##: Used by the Maven Release plugin when releasing XWiki. It generates Javadoc and Source artifacts. It also checks that the Java version used is JDK6, that the Javadoc exists and it signs artifacts using GPG (this is a good practice and a [[requirement for being able to upload some of our artifacts to the Maven Central Repository>>https://maven.apache.org/guides/mini/guide-central-repository-upload.html]]).
Vincent Massol 117.1 162 * ##snapshot##: {{info}}Since 11.8RC1{{/info}} To be used when building snapshots (so never on a release!). Enabling this profile does the following:
Vincent Massol 117.2 163 ** The resulting XWiki Standard packagings includes the XWiki snapshots Extension Repository Source preconfigured and anyone downloading it for local testing will not have to enable it by hand. Distribution Wizard and Extension Manager will thus install the latest published snapshot extension builds and not fail completely saying that it can not find snapshot versions. Note that before version 11.8RC1, the profile used to be named ##snapshotModules## and has been renamed to be more generic.
Vincent Massol 117.1 164 ** Defines automatically the XWiki Maven Repository so that you don't have to modify your Maven ##settings.xml## to have it there. This is useful for tools such as LGTM which need to have the XWiki Maven Remote repo configured. It'll also be useful for simpler developer onboarding when we enable this profile automatically when the version in the ##pom.xml## ends with ##SNAPSHOT## (when we find how to do it! ;)).
Vincent Massol 128.2 165 * ##m2e##: For [[m2eclipse>>https://www.eclipse.org/m2e/]] users. It sets the Eclipse output directory to ##target-eclipse## (instead of ##target##) to prevent race conditions between Maven within Eclipse and Maven on the command line.
Vincent Massol 60.1 166 * ##unix##, ##mac##, ##windows##: These profiles are automatically activated depending on the OS the build is running on. These profiles are useful for the Installers and for functional tests to decide how to start XWiki.
167 * ##macprofiler##, ##winprofiler##: Start [[XWiki for Profiling>>Profiling]] (they require that you set a ##profilePath## property in your ##settings.xml## or on the command line)
168 * ##gwt-test-manual##: allow running GWT unit tests manually
Vincent Massol 73.3 169 * ##debug##: remove JS minification.
Vincent Massol 62.1 170 * ##standalone##: Builds the Rendering Standalone artifact. Note that this profile is activated automatically when performing a release.
Thomas Mortagne 72.1 171 * ##quality##: Runs quality checks that take a long time to execute (e.g. checks Jacoco TPC thresholds)
Vincent Massol 128.2 172 * ##clover##: A profile to use when [[generating Test Coverage reports>>Testing#HTestCoverage]] with [[Clover>>https://www.atlassian.com/software/clover/overview]]. This profile skips execution of Checkstyle, Backward Compatibility and Enforcer plugin checks to speed up the coverage generation and because of potential conflicts between tools. Note that even though we've started using Jacoco for our ##quality## profile we still support Clover. The Clover reports are much nicer than the Jacoco ones and it's thus still useful to be able to generate them.
VincentMassol 1.56 173
Vincent Massol 60.1 174 For example, if you use to include legacy modules and run all integration and functional tests and use Jetty/HSQLDB, you would use:
caveden 32.1 175
Vincent Massol 60.1 176 {{code}}
177 mvn clean install -Plegacy,integration-tests,hsqldb,jetty
178 {{/code}}
Artem Melentyev 1.22 179
Vincent Massol 120.1 180 = Building with Docker =
181
182 XWiki offers a [[Docker image to build XWiki>>https://github.com/xwiki/xwiki-docker-build/tree/master/build]], that is used by [[XWiki's CI>>https://ci.xwiki.org]]. It can also be used to build XWiki locally very easily. If you want to use it, you only need to install Docker and you don't need to have Maven installed or any of the other needed tools need to run XWiki's build (like a given version of Firefox for some old functional tests).
183
184 Check how to [[build with the XWiki Docker build image>>https://github.com/xwiki/xwiki-docker-build/tree/master/build]].
185
Vincent Massol 129.1 186 = Build Cache =
187
188 The XWiki build is using the [[Gradle Maven Extension>>https://docs.gradle.com/enterprise/maven-extension/]] (along with the [[Custom Common User Data Maven Extension>>https://github.com/gradle/gradle-enterprise-build-config-samples/blob/master/common-custom-user-data-maven-extension/README.md]]) to speed up the build by caching locally and remotely the Maven goal outputs.
189
190 The configuration is done in the ##.mvn/extensions.xml##, ##.mvn/gradle-enterprise*.*## files.
191
192 If you need to skip the build caches you can execute Maven with the following system property:
Thomas Mortagne 131.1 193
Vincent Massol 129.1 194 * For the local build cache: [[##-Dgradle.cache.local.enabled=false##>>https://docs.gradle.com/enterprise/maven-extension/#disabling_the_local_cache]]
Vincent Massol 129.2 195 * For the remote build cache: [[##-Dgradle.cache.remote.enabled=false##>>https://docs.gradle.com/enterprise/maven-extension/#disabling_the_remote_cache]]
Vincent Massol 129.1 196
Vincent Massol 60.1 197 = Automatic Checks =
Caleb James DeLisle 44.1 198
Vincent Massol 60.1 199 The XWiki build performs some automated checks:
Manuel Smeria 73.2 200
Vincent Massol 87.1 201 * Style checks with Checkstyle. To skip: ##-Dxwiki.checkstyle.skip=true##. We also have custom Checkstyle checks:
Vincent Massol 96.3 202 ** Verify that ##@Unstable## annotation don't stay too long (and that a ##@since## annotation is present too)
Vincent Massol 87.1 203 ** Verify that Script Services are not located in the ##internal## package
Vincent Massol 109.4 204 ** Verify that ##@since## javadoc tags have the correct format (and that they don't contain several versions per tag). Example of correct format: ##@since 10.8RC1##.
Vincent Massol 125.2 205 * Verify header licenses with the [[Mycila Maven license plugin>>https://github.com/mycila/license-maven-plugin]].
Vincent Massol 128.2 206 * Backward compatibility checks with [[revapi>>https://revapi.org/]]. To skip: ##-Dxwiki.revapi.skip=true##.
Vincent Massol 119.1 207 * Maven Enforcer checks (To skip: ##-Dxwiki.enforcer.skip=true##):
Vincent Massol 87.1 208 ** Verify that all plugins have versions specified
209 ** Verify that we don't use Commons Lang < 3 (i.e. that ##commons-lang:commons-lang## artifact is forbidden)
210 ** Verify the correct JUnit artifact is used (##junit-dep## and not ##junit##)
Vincent Massol 60.1 211 ** Verify we don't use Commons Logging or Log4j (since we use SLF4J)
Vincent Massol 87.1 212 ** Verify that the Java version used to release XWiki is correct (e.g. Java 8 starting with XWiki 8.1, Java 7 for XWiki 6.0 and Java 6 before)
Vincent Massol 60.1 213 ** Verify that Javadoc exist (in the release profile, this is a Maven Central requirement)
214 ** In Commons: Verify that Commons modules don't have a dependency on Rendering and Platform modules
215 ** In Rendering: Verify that Rendering modules don't have a dependency on Platform modules
Thomas Mortagne 100.1 216 * Spoon checks (To skip: ##-Dxwiki.spoon.skip=true##):
217 ** Verify none of the listed methods are called in our Java code
Vincent Massol 119.1 218 ** Verify that ##components.txt## contains all Components
219 ** Verify that JUnit4 and JUnit5 APIs are not both used at the same time in a test
Vincent Massol 122.1 220 ** Verify that the @Inject annotation is done on the component role (fails if not done by error on the component implementation, unless it's using the ##roles## attribute of the ##@Component## annotation and it points to itsself). {{info}}Since 12.4RC1{{/info}}
Vincent Massol 87.1 221 * For XARs, verify format and content using the [[XAR Plugin>>XARPlugin]]
Vincent Massol 87.2 222 * Verify that Test Percentage Coverage don't go down
Vincent Massol 109.3 223 ** This is achieved using Jacoco and the check is done at each module level using a Maven property named ##xwiki.jacoco.instructionRatio##.
Vincent Massol 120.3 224 ** Note: We also perform a global coverage check but [[it's done only in the CI>>dev:Community.ContinuousBuild#HCloverPipeline]]
Vincent Massol 99.1 225 * We check automatically that we don't have wiki pages that require Programming Rights unduly. This is exercised during functional tests. For more details see [[Testing documentation>>Community.Testing||anchor="HFunctionalTesting"]].
Vincent Massol 114.1 226 * Verify Test output
227 ** Verify that JUnit tests don't output content to stdout or stderr. Tests are supposed to either configure the code to not output anything or if it's expected then they're supposed to [[catch the logs and assert them>>dev:Community.Testing.JavaUnitTesting.WebHome#HCapturingandAssertingLogs]]. Note that this check is also executing for JUnit5 tests executed in your IDE (if the ##pom.xml## file in the current directory doesn't have the ##xwiki.surefire.captureconsole.skip## Maven property set to true).
228 ** Verify that functional tests don't contain errors or warnings when they execute. See [[Docker Tests>>Community.Testing.DockerTesting.WebHome||anchor="HStdout2Fstderrvalidationerrors"]] (for JUnit5) and [[Selenium2 Tests>>Community.Testing.WebHome||anchor="HBestpractices"]] (for JUnit4).
Caleb James DeLisle 44.1 229
Thomas Mortagne 81.1 230 = Tips =
Vincent Massol 40.1 231
Vincent Massol 60.1 232 == Skipping Tests ==
Vincent Massol 40.1 233
Vincent Massol 60.1 234 While you should almost never do that, here's a tip for the rare occasions when you'll need to build something fast:
VincentMassol 1.26 235
Vincent Massol 60.1 236 {{code}}
237 mvn install -Dtest=none -DfailIfNoTests=false
238 {{/code}}
VincentMassol 1.28 239
Vincent Massol 60.1 240 Alternatives are ##mvn install -DskipTests=true## or ##mvn install -Dmaven.test.skip=true##. Refere to the Maven documentation to understand the differences.
Vincent Massol 43.3 241
Vincent Massol 40.1 242 = Troubleshooting =
Vincent Massol 38.1 243
Vincent Massol 40.1 244 == Dealing with Out-of-Memory Errors ==
VincentMassol 1.50 245
Vincent Massol 124.1 246 If you get an ##OutOfMemoryError## then increase the maximum heap space by setting the ##MAVEN_OPTS## environment variable. For example:
hritcu 1.48 247
Vincent Massol 47.1 248 {{code language="none"}}
Vincent Massol 124.1 249 MAVEN_OPTS="-Xmx1024m"
Vincent Massol 47.1 250 {{/code}}
251
Vincent Massol 40.1 252 == Error in Windows installer build: Windres error ==
hritcu 1.65 253
VincentMassol 1.75 254 Launch4J is using a binary called Windres which requires that the environment is NOT set to use UTF-8. If you get the following error check your LANG environment variable:
255
Manuel Smeria 73.2 256 {{code language="none"}}
257 Embedded error: net.sf.launch4j.BuilderException: net.sf.launch4j.ExecException: Exec failed(1): /var/tmp/installers/windows/target/dependency/bin/windres --preprocessor=cat -J rc -O coff -F pe-i386 /tmp/launch4j10018rc /tmp/launch4j10019o
258 {{/code}}
VincentMassol 1.75 259
Vincent Massol 40.1 260 == Building behind a proxy ==
malaka 25.1 261
Manuel Smeria 73.2 262 If you are connecting to the Internet through a proxy then you need to modify your ##settings.xml## file so that Maven knows it:
malaka 25.1 263
Vincent Massol 39.1 264 {{code language="xml"}}
malaka 25.1 265 <settings>
266 <proxies>
267 <proxy>
268 <active>true</active>
269 <protocol>http</protocol>
270 <host>host</host>
271 <port>port</port>
Vincent Massol 40.2 272 <username>uname</username>
malaka 25.1 273 <password>password</password>
274 </proxy>
275 </proxies>
276 <!--other tags-->
277 </settings>
Vincent Massol 39.1 278 {{/code}}
malaka 25.1 279
Clemens Robbenhaar 88.1 280 == Errors about missing resources ==
281
282 Some people have reported problems when building XWiki for the first time, or the first time after a version update. The error message is loosely looking like:
283
284 {{code}}
285 [...]
286 [ERROR] Failed to execute goal org.apache.maven.plugins:maven-remote-resources-plugin:1.4:process (xwiki-license-resources) on project [[some-xwiki-project-here]]: Resources archive cannot be found. Could not find artifact org.xwiki.commons:[[some-xwiki-commons-lib]]:jar:x.y.z-SNAPSHOT
287 [ERROR]
288 [ERROR] Try downloading the file manually from the project website.
289 [ERROR]
290 [ERROR] Then, install it using the command:
291 [ERROR] mvn install:install-file -DgroupId=org.xwiki.commons -DartifactId=[[some-xwiki-commons-lib]] -Dversion=x.y.z-SNAPSHOT -Dpackaging=jar -Dfile=/path/to/file
292 [ERROR]
293 [ERROR] Alternatively, if you host your own repository you can deploy the file there:
294 [ERROR] mvn deploy:deploy-file -DgroupId=org.xwiki.commons -DartifactId=[[some-xwiki-commons-lib]] -Dversion=x.y.z-SNAPSHOT -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]
295 [...]
296 {{/code}}
297
Clemens Robbenhaar 89.1 298 This is probably a problem with the maven version; try updating to the recommended maven version and retry.
Denis Gervalle 96.1 299 \\Alternatively just call the maven build a second (or possible even a third time); the problem usually goes away for consecutive builds.
Clemens Robbenhaar 88.1 300
Vincent Massol 128.2 301 If the problem does not go away, check if https://nexus.xwiki.org/ is running. If it is not, please wait a moment until it comes back. (As this is a rather critical part of the infrastructure, you can be pretty sure it gets fixed quickly.)
Clemens Robbenhaar 88.1 302
Vincent Massol 41.1 303 = Build Tools =
304
Vincent Massol 128.3 305 We have developed some build tools in the form of Maven plugins. They are located in the [[##xwiki-commons/xwiki-commons-tools##>>https://github.com/xwiki/xwiki-commons/tree/master/xwiki-commons-tools]] and [[##xwiki-platform/xwiki-platform-tools/##>>https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-tools]] directories. Here are descriptions of some of them:
Manuel Smeria 73.2 306
Vincent Massol 51.3 307 * ##xwiki-packager-plugin##: Takes XWiki pages defined as XML files and located in ##src/main/resources/## and load them into a database (defined by ##src/main/packager/hibernate.cfg.xml##). An example usage is available [[here>>https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-tools/xwiki-platform-tool-packager-plugin/src/it/basic-import-export]].
Vincent Massol 75.1 308 * ##[[xwiki-xar-plugin>>XARPlugin]]##: Takes XWiki pages defined as XML files and located in ##src/main/resources/## and generates a XAR (ZIP format) out of them.
Thomas Mortagne 92.1 309 * ##[[xwiki-extension-plugin>>ExtensionPlugin]]##: Various extension oriented mojos for Maven build. Current mostly about generating extensions descriptors (.xed) in various situations (WAR dependencies, etc.).
Thomas Mortagne 94.1 310 * ##[[xwiki-commons-tool-webjar-handlers>>WebJarHandler]]##: A handler for Maven type ##webjar## to use to produce explicitly typed and standard webjar artifacts.
Vincent Massol 103.1 311 * ##[[xwiki-platform-tool-provision-plugin>>ProvisionPlugin]]##: Installs Extensions into a running XWiki instance
Thomas Mortagne 106.1 312 * ##[[xwiki-commons-tool-remote-resource-plugin>>XWikiRemoteResourcePlugin]]##: A more memory friendly alternative to standard Maven Remote Resource Plugin
Vincent Massol 41.1 313
Denis Gervalle 96.1 314 Also, you can find some contrib tools:
Thomas Mortagne 97.1 315
Denis Gervalle 96.1 316 * [[Off-line XWiki Repository Packager Maven Plugin>>https://github.com/xwiki-contrib/maven-plugin-offline-xwiki-repository-packager]]
317
Vincent Massol 40.1 318 = Building in Eclipse =
Jean-Vincent Drean 35.1 319
Vincent Massol 39.1 320 * [[BuildingInEclipse]]
VincentMassol 1.4 321
Vincent Massol 40.1 322 = Building in IntelliJ IDEA =
serasset 1.19 323
Vincent Massol 39.1 324 * [[BuildingInIdea]]
Vincent Massol 66.1 325
326 = Creating a Build for your own Modules =
327
328 == Generating a XAR ==
329
Vincent Massol 67.1 330 Follow these steps:
Manuel Smeria 73.2 331
Vincent Massol 66.1 332 * Put the XWiki XML files into the ##src/main/resources## directory
333 * Use the ##xar## packaging in the your ##pom.xml##.
334 * Make sure the XAR packaging extension is registered in Maven.
335
336 For example:
Vincent Massol 66.2 337
Vincent Massol 66.1 338 {{code language="xml"}}
339 <project...>
340 ...
341 <packaging>xar</packaging>
342 ...
343 <build>
344 <extensions>
345 <!-- Needed to add support for the "xar" packaging -->
346 <extension>
347 <groupId>org.xwiki.commons</groupId>
348 <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
349 <version>(version to use)</version>
350 </extension>
351 </extensions>
352 </build>
353 ...
354 </project>
355 {{/code}}
356
Manuel Smeria 73.2 357 Make sure you run ##mvn xar:format## to ensure your XWiki XML files are properly formatted, following [[XWiki XML files best practices>>XWikiXMLFilesCodeStyle]].
Jean SIMARD 78.1 358
359 = Building a patched version =
360
Vincent Massol 128.2 361 If you want to patch a part of XWiki without compiling the entire software, you may take a look at the following [[blog article>>https://hole.tuziwo.info/patch-a-dependency-of-maven.html]]. It explains how to patch and compile only the JAR archive you want, without building all of the JAR archives of XWiki.
Vincent Massol 132.1 362
363 = Gradle Enterprise Cache =
364
365 In order to speed up the XWiki Maven builds (either on the dev machines or on the CI), we use a [[Gradle Enterprise Cache>>https://docs.gradle.com/enterprise/tutorials/caching/]].
366
367 This is the setup for XWiki:
368 * In each Commons, Rendering, Platform source repos, inside ##.mvn## there are 3 files:
369 ** ##extensions.xml##: Declares the Gradle extension to Maven
370 ** ##gradle-enterprise.xml##: Configuration for Gradle Enterprise
371 ** ##gradle-enterprise-custom-user-data.groovy##: Custom configuration for Gradle Enterprise to set the Maven profiles as ge.xwiki.org tags
372 * In the Jenkins Docker Cloud configuration, we bind a volume from the agent host to pass credential keys to authenticate the CI against ge.xwiki.org
373 * On each agent host, the Maven ##settings.xml## (mounted as a volume for the Docker Cloud build image) contains a ##<server>## entry with credentials for the remote cache
374 * In the ##xwikiBuild.groovy## Jenkins pipeline, we pass a system property to disable caching fingerprints as it costs more to download them from the remote cache than to recompute them (it slows down the build otherwise)
375

Get Connected