Wiki source code of Building XWiki from sources

Last modified by Lucas Charpentier (Sereza7) on 2024/01/19 11:27

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
Simon Urli 145.1 8 ** e.g. Use Java 8 for XWiki < 14.0, Java 11 for 14.0 =< XWiki < 16.0.0 and Java 17 for XWiki >= 16.0.0
9 * Make sure you install a Maven version >= 3.6.3. Note that our [[CI>>https://ci.xwiki.org]] builds XWiki using Maven 3.9.6 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
Simon Urli 145.1 29 * Install [[Maven 3.9.6 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 )))
Sergei Kulagin 137.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 ##.m2## directory in your ##%USERPROFILE%## directory, e.g. ##C:\Users\YourUserName\.m2##. If you cannot do this from Windows Explorer, open a command line and execute command ##md .m2## from inside of the ##%USERPROFILE%## directory.(((
Vincent Massol 85.1 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
Simon Urli 144.1 120 Now that you have installed Maven and checked out the [[Projects>>SourceRepository||anchor="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
Simon Urli 144.1 126 Thanks to XWiki's [[Continuous Integration setup>>DevelopmentPractices||anchor="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
Simon Urli 144.1 145 * ##legacy##: Includes the [[legacy modules>>DevelopmentPractices||anchor="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 )))
Thomas Mortagne 97.1 154 * ##distribution##: {{info}}Since 9.5RC1{{/info}} Also build distribution packages (the WAR, the flavor, the jetty/hsqldb package, etc)
Vincent Massol 110.1 155 ** ##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 156
Vincent Massol 60.1 157 More "exotic" ones:
Manuel Smeria 73.2 158
Vincent Massol 128.2 159 * ##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 160 * ##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 161 ** 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 162 ** 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 163 * ##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 164 * ##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.
165 * ##macprofiler##, ##winprofiler##: Start [[XWiki for Profiling>>Profiling]] (they require that you set a ##profilePath## property in your ##settings.xml## or on the command line)
166 * ##gwt-test-manual##: allow running GWT unit tests manually
Vincent Massol 73.3 167 * ##debug##: remove JS minification.
Vincent Massol 62.1 168 * ##standalone##: Builds the Rendering Standalone artifact. Note that this profile is activated automatically when performing a release.
Thomas Mortagne 72.1 169 * ##quality##: Runs quality checks that take a long time to execute (e.g. checks Jacoco TPC thresholds)
Simon Urli 144.1 170 * ##clover##: A profile to use when [[generating Test Coverage reports>>Testing||anchor="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 171
Vincent Massol 60.1 172 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 173
Vincent Massol 60.1 174 {{code}}
175 mvn clean install -Plegacy,integration-tests,hsqldb,jetty
176 {{/code}}
Artem Melentyev 1.22 177
Vincent Massol 120.1 178 = Building with Docker =
179
180 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).
181
182 Check how to [[build with the XWiki Docker build image>>https://github.com/xwiki/xwiki-docker-build/tree/master/build]].
183
Vincent Massol 129.1 184 = Build Cache =
185
186 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.
187
188 The configuration is done in the ##.mvn/extensions.xml##, ##.mvn/gradle-enterprise*.*## files.
189
190 If you need to skip the build caches you can execute Maven with the following system property:
Thomas Mortagne 131.1 191
Vincent Massol 129.1 192 * 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 193 * 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 194
Vincent Massol 60.1 195 = Automatic Checks =
Caleb James DeLisle 44.1 196
Vincent Massol 60.1 197 The XWiki build performs some automated checks:
Manuel Smeria 73.2 198
Vincent Massol 137.2 199 * Style checks with Checkstyle. To skip: ##-Dxwiki.checkstyle.skip=true##. To run on the command line: ##mvn checkstyle:check@default -fae | grep ERROR##. We have the following custom Checkstyle checks:
Vincent Massol 96.3 200 ** Verify that ##@Unstable## annotation don't stay too long (and that a ##@since## annotation is present too)
Vincent Massol 87.1 201 ** Verify that Script Services are not located in the ##internal## package
Vincent Massol 109.4 202 ** 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 203 * Verify header licenses with the [[Mycila Maven license plugin>>https://github.com/mycila/license-maven-plugin]].
Vincent Massol 128.2 204 * Backward compatibility checks with [[revapi>>https://revapi.org/]]. To skip: ##-Dxwiki.revapi.skip=true##.
Vincent Massol 119.1 205 * Maven Enforcer checks (To skip: ##-Dxwiki.enforcer.skip=true##):
Vincent Massol 87.1 206 ** Verify that all plugins have versions specified
207 ** Verify that we don't use Commons Lang < 3 (i.e. that ##commons-lang:commons-lang## artifact is forbidden)
208 ** Verify the correct JUnit artifact is used (##junit-dep## and not ##junit##)
Vincent Massol 60.1 209 ** Verify we don't use Commons Logging or Log4j (since we use SLF4J)
Vincent Massol 87.1 210 ** 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 211 ** Verify that Javadoc exist (in the release profile, this is a Maven Central requirement)
212 ** In Commons: Verify that Commons modules don't have a dependency on Rendering and Platform modules
213 ** In Rendering: Verify that Rendering modules don't have a dependency on Platform modules
Thomas Mortagne 100.1 214 * Spoon checks (To skip: ##-Dxwiki.spoon.skip=true##):
215 ** Verify none of the listed methods are called in our Java code
Vincent Massol 119.1 216 ** Verify that ##components.txt## contains all Components
217 ** Verify that JUnit4 and JUnit5 APIs are not both used at the same time in a test
Thomas Mortagne 135.1 218 ** 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}}(((
Simon Urli 134.1 219 {{info}}
220 It's possible to add exceptions on this check for some specific cases (e.g. injecting an external interface that we don't control). Exceptions are configured in the ##pom.xml## with a configuration such as:
221
Thomas Mortagne 136.1 222 {{code language="xml"}}
Simon Urli 133.1 223 <build>
224 <plugins>
225 <plugin>
226 <groupId>fr.inria.gforge.spoon</groupId>
227 <artifactId>spoon-maven-plugin</artifactId>
228 <executions>
229 <execution>
230 <id>spoon-main</id>
231 <configuration>
232 <processorProperties combine.children="append">
233 <processorProperty>
234 <name>org.xwiki.tool.spoon.InjectAnnotationProcessor</name>
235 <properties>
236 <property>
237 <!-- Exclude javax.script.ScriptEngineFactory since it's not an XWiki interface and thus
238 doesn't have a @Role annotation. there's no way for the Spoon checker to find
239 out about this, since only the Component Manager knows what has been registered for it. -->
240 <name>excludedFieldTypes</name>
241 <value><![CDATA[
242 ["javax.script.ScriptEngineFactory"]
243 ]]></value>
244 </property>
245 </properties>
246 </processorProperty>
247 </processorProperties>
248 </configuration>
249 </execution>
250 </executions>
251 </plugin>
252 </plugins>
253 </build>
Simon Urli 134.1 254 {{/code}}
255 {{/info}}
Thomas Mortagne 135.1 256 )))
Simon Urli 134.1 257
Vincent Massol 87.1 258 * For XARs, verify format and content using the [[XAR Plugin>>XARPlugin]]
Vincent Massol 87.2 259 * Verify that Test Percentage Coverage don't go down
Vincent Massol 109.3 260 ** This is achieved using Jacoco and the check is done at each module level using a Maven property named ##xwiki.jacoco.instructionRatio##.
Simon Urli 144.1 261 ** Note: We also perform a global coverage check but [[it's done only in the CI>>dev:Community.ContinuousBuild||anchor="HCloverPipeline"]]
Vincent Massol 99.1 262 * 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 263 * Verify Test output
Simon Urli 144.1 264 ** 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||anchor="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).
Vincent Massol 114.1 265 ** 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).
Vincent Massol 140.1 266 * Verify code quality with SonarQube. This is achieved using [[SonarCloud.io>>https://sonarcloud.io/organizations/xwiki/projects]] which is [[configured>>https://sonarcloud.io/organizations/xwiki/quality_gates/show/43654]] so that any Blocker severity issue on new code (i.e. code that is less than 30 days old) fails the XWiki CI build.
Caleb James DeLisle 44.1 267
Thomas Mortagne 81.1 268 = Tips =
Vincent Massol 40.1 269
Vincent Massol 60.1 270 == Skipping Tests ==
Vincent Massol 40.1 271
Vincent Massol 60.1 272 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 273
Vincent Massol 60.1 274 {{code}}
275 mvn install -Dtest=none -DfailIfNoTests=false
276 {{/code}}
VincentMassol 1.28 277
Vincent Massol 60.1 278 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 279
Vincent Massol 40.1 280 = Troubleshooting =
Vincent Massol 38.1 281
Vincent Massol 40.1 282 == Dealing with Out-of-Memory Errors ==
VincentMassol 1.50 283
Vincent Massol 124.1 284 If you get an ##OutOfMemoryError## then increase the maximum heap space by setting the ##MAVEN_OPTS## environment variable. For example:
hritcu 1.48 285
Vincent Massol 47.1 286 {{code language="none"}}
Vincent Massol 124.1 287 MAVEN_OPTS="-Xmx1024m"
Vincent Massol 47.1 288 {{/code}}
289
Vincent Massol 40.1 290 == Error in Windows installer build: Windres error ==
hritcu 1.65 291
VincentMassol 1.75 292 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:
293
Manuel Smeria 73.2 294 {{code language="none"}}
295 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
296 {{/code}}
VincentMassol 1.75 297
Vincent Massol 40.1 298 == Building behind a proxy ==
malaka 25.1 299
Manuel Smeria 73.2 300 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 301
Vincent Massol 39.1 302 {{code language="xml"}}
malaka 25.1 303 <settings>
304 <proxies>
305 <proxy>
306 <active>true</active>
307 <protocol>http</protocol>
308 <host>host</host>
309 <port>port</port>
Vincent Massol 40.2 310 <username>uname</username>
malaka 25.1 311 <password>password</password>
312 </proxy>
313 </proxies>
314 <!--other tags-->
315 </settings>
Vincent Massol 39.1 316 {{/code}}
malaka 25.1 317
Clemens Robbenhaar 88.1 318 == Errors about missing resources ==
319
320 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:
321
322 {{code}}
323 [...]
324 [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
325 [ERROR]
326 [ERROR] Try downloading the file manually from the project website.
327 [ERROR]
328 [ERROR] Then, install it using the command:
329 [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
330 [ERROR]
331 [ERROR] Alternatively, if you host your own repository you can deploy the file there:
332 [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]
333 [...]
334 {{/code}}
335
Clemens Robbenhaar 89.1 336 This is probably a problem with the maven version; try updating to the recommended maven version and retry.
Denis Gervalle 96.1 337 \\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 338
Vincent Massol 128.2 339 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 340
Vincent Massol 41.1 341 = Build Tools =
342
Vincent Massol 128.3 343 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 344
Vincent Massol 51.3 345 * ##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 346 * ##[[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 347 * ##[[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 348 * ##[[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 349 * ##[[xwiki-platform-tool-provision-plugin>>ProvisionPlugin]]##: Installs Extensions into a running XWiki instance
Thomas Mortagne 106.1 350 * ##[[xwiki-commons-tool-remote-resource-plugin>>XWikiRemoteResourcePlugin]]##: A more memory friendly alternative to standard Maven Remote Resource Plugin
Vincent Massol 41.1 351
Denis Gervalle 96.1 352 Also, you can find some contrib tools:
Thomas Mortagne 97.1 353
Denis Gervalle 96.1 354 * [[Off-line XWiki Repository Packager Maven Plugin>>https://github.com/xwiki-contrib/maven-plugin-offline-xwiki-repository-packager]]
355
Vincent Massol 40.1 356 = Building in Eclipse =
Jean-Vincent Drean 35.1 357
Vincent Massol 39.1 358 * [[BuildingInEclipse]]
VincentMassol 1.4 359
Vincent Massol 40.1 360 = Building in IntelliJ IDEA =
serasset 1.19 361
Vincent Massol 39.1 362 * [[BuildingInIdea]]
Vincent Massol 66.1 363
364 = Creating a Build for your own Modules =
365
366 == Generating a XAR ==
367
Vincent Massol 67.1 368 Follow these steps:
Manuel Smeria 73.2 369
Vincent Massol 66.1 370 * Put the XWiki XML files into the ##src/main/resources## directory
371 * Use the ##xar## packaging in the your ##pom.xml##.
372 * Make sure the XAR packaging extension is registered in Maven.
373
374 For example:
Vincent Massol 66.2 375
Vincent Massol 66.1 376 {{code language="xml"}}
377 <project...>
378 ...
379 <packaging>xar</packaging>
380 ...
381 <build>
382 <extensions>
383 <!-- Needed to add support for the "xar" packaging -->
384 <extension>
385 <groupId>org.xwiki.commons</groupId>
386 <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
387 <version>(version to use)</version>
388 </extension>
389 </extensions>
390 </build>
391 ...
392 </project>
393 {{/code}}
394
Manuel Smeria 73.2 395 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 396
397 = Building a patched version =
398
Vincent Massol 128.2 399 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 400
401 = Gradle Enterprise Cache =
402
403 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/]].
404
405 This is the setup for XWiki:
Simon Urli 133.1 406
Vincent Massol 132.1 407 * In each Commons, Rendering, Platform source repos, inside ##.mvn## there are 3 files:
408 ** ##extensions.xml##: Declares the Gradle extension to Maven
409 ** ##gradle-enterprise.xml##: Configuration for Gradle Enterprise
410 ** ##gradle-enterprise-custom-user-data.groovy##: Custom configuration for Gradle Enterprise to set the Maven profiles as ge.xwiki.org tags
411 * 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
Vincent Massol 139.1 412 * On each agent host, there's a ##.m2/.gradle-enterprise/keys.properties## file with an access key from the ##ci## user on ge.xwiki.org (mounted as a volume for the Docker Cloud build image : ##type=bind,source=/home/hudsonagent/.m2/.gradle-enterprise/keys.properties,destination=/root/.m2/.gradle-enterprise/keys.properties##)
Vincent Massol 132.1 413 * 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)

Get Connected