Wiki source code of Building XWiki from sources

Last modified by Vincent Massol on 2026/07/23 23:38

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Children
- Content
- Attachments
- History
- Information
- Likes

version	line-number	content
73.2	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
1.1	4
125.1	5	= Build Requirements =
	6
130.1	7	* See [[Java support>>Community.SupportStrategy.JavaSupportStrategy.WebHome\|\|anchor="HByXWikiVersions"]] to find which version to build XWiki with
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
154.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.9.11 and thus this is our recommended version.
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.
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]].
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]].
46.2	16
40.1	17	= Understanding the directory structure =
1.5	18
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! ;-)
1.2	20
60.1	21	The first thing to understand is the [[directory structure we use>>SourceRepository]].
1.2	22
40.1	23	= Checking out the sources =
1.6	24
60.1	25	Use your favorite SCM client to [[check out the Project>>SourceRepository]] you wish to build.
1.6	26
40.1	27	= Installing Maven =
1.4	28
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.(((
73.2	30	{{info}}
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/]].
73.2	32	{{/info}}
40.1	33	)))
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##):(((
73.2	35	{{code language="none"}}
124.1	36	MAVEN_OPTS="-Xmx1024m"
73.2	37	{{/code}}
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.
81.1	40	)))
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.(((
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
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/]].
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
39.1	52	{{code language="xml"}}
1.30	53	<settings>
	54	<profiles>
	55	<profile>
	56	<id>xwiki</id>
	57	<repositories>
	58	<repository>
53.1	59	<id>xwiki-snapshots</id>
146.2	60	<name>XWiki Nexus Snapshot Repository</name>
	61	<url>https://nexus-snapshots.xwiki.org/repository/snapshots/</url>
53.1	62	<releases>
	63	<enabled>false</enabled>
	64	</releases>
	65	<snapshots>
	66	<enabled>true</enabled>
	67	</snapshots>
	68	</repository>
	69	<repository>
52.1	70	<id>xwiki-releases</id>
	71	<name>XWiki Nexus Releases Repository Proxy</name>
152.1	72	<url>https://nexus-snapshots.xwiki.org/repository/public-proxy</url>
52.1	73	<releases>
	74	<enabled>true</enabled>
	75	</releases>
	76	<snapshots>
	77	<enabled>false</enabled>
	78	</snapshots>
	79	</repository>
53.1	80	</repositories>
	81	<pluginRepositories>
	82	<pluginRepository>
98.1	83	<id>xwiki-snapshots</id>
146.2	84	<name>XWiki Nexus Plugin Snapshot Repository</name>
	85	<url>https://nexus-snapshots.xwiki.org/repository/snapshots/</url>
52.1	86	<releases>
	87	<enabled>false</enabled>
	88	</releases>
	89	<snapshots>
	90	<enabled>true</enabled>
	91	</snapshots>
53.1	92	</pluginRepository>
52.1	93	<pluginRepository>
98.1	94	<id>xwiki-releases</id>
52.1	95	<name>XWiki Nexus Plugin Releases Repository Proxy</name>
152.1	96	<url>https://nexus-snapshots.xwiki.org/repository/public-proxy</url>
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
73.2	113	{{info}}
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]].
81.1	115	{{/info}}
40.1	116	)))
9.1	117
40.1	118	= Building with Maven =
34.2	119
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:
31.1	121
60.2	122	{{code}}
	123	mvn clean install
	124	{{/code}}
	125
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:
73.2	127
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)
60.1	129	* In a subdirectory of that module, called ##target##.
31.1	130
60.1	131	{{warning}}
83.2	132	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).
60.1	133	{{/warning}}
38.1	134
155.1	135	{{info}}
	136	Depending on which version of XWiki you are building, you will generally need to use [[the right Java version>>https://dev.xwiki.org/xwiki/bin/view/Community/SupportStrategy/JavaSupportStrategy/#HByXWikiVersions]]. A script exist to automatically switch the right Java version dependending on the pom you are building, see [[Community.DevelopmentTools\|\|anchor="HXWikiscripts"]] for more details and especially the ##xmvn## tool.
	137	{{/info}}
	138
151.1	139	{{info title="Handling proper locale"}}
	140	Note that some tests in XWiki requires that the system locale is set to en_US (e.g. for checking some date formats). If you obtain failures that seems to be related to a locale problem you can try to run the following maven command:
	141	{{code language="bash"}}LANG=C.UTF-8 mvn clean install{{/code}}
	142	{{/info}}
	143
60.1	144	== Using Profiles ==
1.56	145
128.2	146	Project builds define several [[Maven Profiles>>https://maven.apache.org/guides/introduction/introduction-to-profiles.html]]. We've standardized their names across Projects.
39.1	147
60.1	148	Here are the most common ones:
73.2	149
144.1	150	* ##legacy##: Includes the [[legacy modules>>DevelopmentPractices\|\|anchor="HDeprecationRules"]] in the build.
60.1	151	* ##integration-tests##: Executes integration and functional tests in the build.
110.1	152	** ##docker##: Executes integration tests that are Docker-based. You'll need to have Docker installed for this to work.
60.1	153	* ##jetty##, ##glassfish##: Run the build for the specified container (##jetty## is the default when not specified).
81.1	154	* ##hsqldb## (Hypersonic SQL), ##mysql## (MySQL), ##pgsql## (PostgreSQL), ##derby## (Derby): Run the build for the specified database (##hsqldb## is the default when not specified).(((
60.1	155	{{warning}}
	156	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.
39.1	157	{{/warning}}
60.1	158	)))
158.1	159	* ##distribution##: Also build distribution packages (the WAR, the flavor, the jetty/hsqldb package, etc)
	160	** ##flavor-integration-tests##: Execute integration and functional tests related to the the default flavor located in ##xwiki-platform##.
1.60	161
60.1	162	More "exotic" ones:
73.2	163
157.1	164	* ##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 supported by the branch>>doc:Community.SupportStrategy.JavaSupportStrategy.WebHome]], 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]]).
158.1	165	* ##snapshot##: To be used when building snapshots (so never on a release!). Enabling this profile does the following:
159.1	166	** 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 cannot find snapshot versions.
117.1	167	** 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! ;)).
128.2	168	* ##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.
60.1	169	* ##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.
	170	* ##macprofiler##, ##winprofiler##: Start [[XWiki for Profiling>>Profiling]] (they require that you set a ##profilePath## property in your ##settings.xml## or on the command line)
	171	* ##gwt-test-manual##: allow running GWT unit tests manually
73.3	172	* ##debug##: remove JS minification.
62.1	173	* ##standalone##: Builds the Rendering Standalone artifact. Note that this profile is activated automatically when performing a release.
72.1	174	* ##quality##: Runs quality checks that take a long time to execute (e.g. checks Jacoco TPC thresholds)
144.1	175	* ##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.
1.56	176
60.1	177	For example, if you use to include legacy modules and run all integration and functional tests and use Jetty/HSQLDB, you would use:
32.1	178
60.1	179	{{code}}
	180	mvn clean install -Plegacy,integration-tests,hsqldb,jetty
	181	{{/code}}
1.22	182
120.1	183	= Building with Docker =
	184
	185	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).
	186
	187	Check how to [[build with the XWiki Docker build image>>https://github.com/xwiki/xwiki-docker-build/tree/master/build]].
	188
129.1	189	= Build Cache =
	190
148.1	191	The XWiki build is using the [[Develocity Maven Extension>>https://docs.gradle.com/enterprise/maven-extension/]] (along with the [[Custom Common User Data Maven Extension>>https://github.com/gradle/common-custom-user-data-maven-extension/blob/main/README.md]]) to speed up the build by caching locally and remotely the Maven goal outputs.
129.1	192
148.1	193	The configuration is done in the ##.mvn/extensions.xml##, ##.mvn/develocity.## files.
129.1	194
	195	If you need to skip the build caches you can execute Maven with the following system property:
131.1	196
147.1	197	* For the local build cache: [[##-Ddevelocity.cache.local.enabled=false##>>https://docs.gradle.com/enterprise/maven-extension/#disabling_the_local_cache]]
	198	* For the remote build cache: [[##-Ddevelocity.cache.remote.enabled=false##>>https://docs.gradle.com/enterprise/maven-extension/#disabling_the_remote_cache]]
129.1	199
60.1	200	= Automatic Checks =
44.1	201
60.1	202	The XWiki build performs some automated checks:
73.2	203
137.2	204	* 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:
96.3	205	** Verify that ##@Unstable## annotation don't stay too long (and that a ##@since## annotation is present too)
87.1	206	** Verify that Script Services are not located in the ##internal## package
109.4	207	** 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##.
125.2	208	* Verify header licenses with the [[Mycila Maven license plugin>>https://github.com/mycila/license-maven-plugin]].
128.2	209	* Backward compatibility checks with [[revapi>>https://revapi.org/]]. To skip: ##-Dxwiki.revapi.skip=true##.
119.1	210	* Maven Enforcer checks (To skip: ##-Dxwiki.enforcer.skip=true##):
87.1	211	** Verify that all plugins have versions specified
	212	** Verify that we don't use Commons Lang < 3 (i.e. that ##commons-lang:commons-lang## artifact is forbidden)
	213	** Verify the correct JUnit artifact is used (##junit-dep## and not ##junit##)
60.1	214	** Verify we don't use Commons Logging or Log4j (since we use SLF4J)
87.1	215	** 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)
60.1	216	** Verify that Javadoc exist (in the release profile, this is a Maven Central requirement)
	217	** In Commons: Verify that Commons modules don't have a dependency on Rendering and Platform modules
	218	** In Rendering: Verify that Rendering modules don't have a dependency on Platform modules
100.1	219	* Spoon checks (To skip: ##-Dxwiki.spoon.skip=true##):
	220	** Verify none of the listed methods are called in our Java code
119.1	221	** Verify that ##components.txt## contains all Components
	222	** Verify that JUnit4 and JUnit5 APIs are not both used at the same time in a test
162.1	223	** {{version since="18.5.0RC1"}}Verify that tests don't leak files outside of their Maven ##target## directory{{/version}}
162.2	224	** 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 itself).(((
134.1	225	{{info}}
162.2	226	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:
134.1	227
136.1	228	{{code language="xml"}}
133.1	229	<build>
	230	<plugins>
	231	<plugin>
	232	<groupId>fr.inria.gforge.spoon</groupId>
	233	<artifactId>spoon-maven-plugin</artifactId>
	234	<executions>
	235	<execution>
	236	<id>spoon-main</id>
	237	<configuration>
	238	<processorProperties combine.children="append">
	239	<processorProperty>
	240	<name>org.xwiki.tool.spoon.InjectAnnotationProcessor</name>
	241	<properties>
	242	<property>
	243	<!-- Exclude javax.script.ScriptEngineFactory since it's not an XWiki interface and thus
	244	doesn't have a @Role annotation. there's no way for the Spoon checker to find
	245	out about this, since only the Component Manager knows what has been registered for it. -->
	246	<name>excludedFieldTypes</name>
	247	<value><![CDATA[
	248	["javax.script.ScriptEngineFactory"]
	249	]]></value>
	250	</property>
	251	</properties>
	252	</processorProperty>
	253	</processorProperties>
	254	</configuration>
	255	</execution>
	256	</executions>
	257	</plugin>
	258	</plugins>
	259	</build>
134.1	260	{{/code}}
	261	{{/info}}
135.1	262	)))
87.1	263	* For XARs, verify format and content using the [[XAR Plugin>>XARPlugin]]
87.2	264	* Verify that Test Percentage Coverage don't go down
109.3	265	** This is achieved using Jacoco and the check is done at each module level using a Maven property named ##xwiki.jacoco.instructionRatio##.
144.1	266	** Note: We also perform a global coverage check but [[it's done only in the CI>>dev:Community.ContinuousBuild\|\|anchor="HCloverPipeline"]]
99.1	267	* 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"]].
114.1	268	* Verify Test output
144.1	269	** 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).
114.1	270	** 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).
163.1	271	*** {{info}}This test is [[currently disabled>>https://github.com/xwiki/xwiki-platform/blob/2ef68dc65cf46f9251673bf4ec898eecd0f96d87/xwiki-platform-core/xwiki-platform-test/xwiki-platform-test-integration/src/main/java/org/xwiki/test/integration/junit/LogCaptureValidator.java#L44-L56]] and needs to be put back in the future{{/info}}
	272	*** However, there are still 2 verifications done. Namely that the following strings don't appear in the output of tests:
	273	**** ##Deprecated usage of## (catches deprecated usages in Velocity)
	274	**** ##because there was insufficient free space available after evicting expired cache entries## (catches Tomcat ##cacheMaxSize## when it's too small, to allow us to review it and increase if need be)
140.1	275	* 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.
164.1	276	* {{version since="18.7.0RC1"}}Inside Legacy modules, verify that the aspects are correctly weaved (using xlint = error), in order to make sure that backward compatibility is effective.{{/version}}
44.1	277
81.1	278	= Tips =
40.1	279
60.1	280	== Skipping Tests ==
40.1	281
60.1	282	While you should almost never do that, here's a tip for the rare occasions when you'll need to build something fast:
1.26	283
60.1	284	{{code}}
	285	mvn install -Dtest=none -DfailIfNoTests=false
	286	{{/code}}
1.28	287
60.1	288	Alternatives are ##mvn install -DskipTests=true## or ##mvn install -Dmaven.test.skip=true##. Refere to the Maven documentation to understand the differences.
43.3	289
150.1	290	== Minimal build requirements ==
	291
150.2	292	Time can be lacking to build the full project before commiting a change. Given that our CI makes these checks later on, it's sometimes possible to avoid building the full project. One should not rely on the CI to catch build fails. Build fails should be addressed before CI and no commit should fail the build.
150.1	293	For any change you commit, you must at the very least:
150.2	294
150.1	295	1. Build the modules where those changes happen.
	296	1. Build the integration tests in this module.
150.3	297	1. Build any other integration tests that are related to the changes.
150.1	298
150.2	299	Here is an example of the minimum maven builds one should run to check a small change in ##xwiki-platform-flamingo-skin-resources##:
	300
150.1	301	1. ##mvn clean install -f xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-resources -Pquality##
	302	1. ##mvn clean install -f xwiki-platform-core/xwiki-platform-flamingo/xwiki-platform-flamingo-skin/xwiki-platform-flamingo-skin-test -Pintegration-tests,docker##
	303	1. The changes are related to the concept of panels, so we also build ##mvn clean install -f xwiki-platform-core/xwiki-platform-panels/xwiki-platform-panels-test -Pintegration-tests,docker##
	304
150.4	305	If you're creating a Pull Request (PR), make sure you keep a written records of what tests you ran and to indicate them in the dedicated section of the PR template that must be filled up with details about the builds ran and the tests passed.
150.1	306
40.1	307	= Troubleshooting =
38.1	308
40.1	309	== Dealing with Out-of-Memory Errors ==
1.50	310
124.1	311	If you get an ##OutOfMemoryError## then increase the maximum heap space by setting the ##MAVEN_OPTS## environment variable. For example:
1.48	312
47.1	313	{{code language="none"}}
124.1	314	MAVEN_OPTS="-Xmx1024m"
47.1	315	{{/code}}
	316
40.1	317	== Error in Windows installer build: Windres error ==
1.65	318
1.75	319	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:
	320
73.2	321	{{code language="none"}}
	322	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
	323	{{/code}}
1.75	324
40.1	325	== Building behind a proxy ==
25.1	326
73.2	327	If you are connecting to the Internet through a proxy then you need to modify your ##settings.xml## file so that Maven knows it:
25.1	328
39.1	329	{{code language="xml"}}
25.1	330	<settings>
	331	<proxies>
	332	<proxy>
	333	<active>true</active>
	334	<protocol>http</protocol>
	335	<host>host</host>
	336	<port>port</port>
40.2	337	<username>uname</username>
25.1	338	<password>password</password>
	339	</proxy>
	340	</proxies>
	341	<!--other tags-->
	342	</settings>
39.1	343	{{/code}}
25.1	344
88.1	345	== Errors about missing resources ==
	346
	347	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:
	348
	349	{{code}}
	350	[...]
	351	[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
	352	[ERROR]
	353	[ERROR] Try downloading the file manually from the project website.
	354	[ERROR]
	355	[ERROR] Then, install it using the command:
	356	[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
	357	[ERROR]
	358	[ERROR] Alternatively, if you host your own repository you can deploy the file there:
	359	[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]
	360	[...]
	361	{{/code}}
	362
89.1	363	This is probably a problem with the maven version; try updating to the recommended maven version and retry.
96.1	364	\\Alternatively just call the maven build a second (or possible even a third time); the problem usually goes away for consecutive builds.
88.1	365
128.2	366	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.)
88.1	367
41.1	368	= Build Tools =
	369
128.3	370	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:
73.2	371
51.3	372	* ##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]].
75.1	373	* ##[[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.
92.1	374	* ##[[xwiki-extension-plugin>>ExtensionPlugin]]##: Various extension oriented mojos for Maven build. Current mostly about generating extensions descriptors (.xed) in various situations (WAR dependencies, etc.).
160.1	375	* ##[[xwiki-platform-tool-security-plugin>>SecurityPlugin]]##: Allow checking security vulnerabilities at runtime
94.1	376	* ##[[xwiki-commons-tool-webjar-handlers>>WebJarHandler]]##: A handler for Maven type ##webjar## to use to produce explicitly typed and standard webjar artifacts.
156.1	377	* ##[[xwiki-commons-tool-webjar-node-handlers>>Community.WebJar Node Maven Handler.WebHome]]##: A handler for Maven type ##webjar##, with additional helper to produce the artifacts using [[node>>https://nodejs.org/]] and [[pnpm>>https://pnpm.io/]].
103.1	378	* ##[[xwiki-platform-tool-provision-plugin>>ProvisionPlugin]]##: Installs Extensions into a running XWiki instance
106.1	379	* ##[[xwiki-commons-tool-remote-resource-plugin>>XWikiRemoteResourcePlugin]]##: A more memory friendly alternative to standard Maven Remote Resource Plugin
41.1	380
96.1	381	Also, you can find some contrib tools:
97.1	382
96.1	383	* [[Off-line XWiki Repository Packager Maven Plugin>>https://github.com/xwiki-contrib/maven-plugin-offline-xwiki-repository-packager]]
	384
40.1	385	= Building in Eclipse =
35.1	386
39.1	387	* [[BuildingInEclipse]]
1.4	388
40.1	389	= Building in IntelliJ IDEA =
1.19	390
39.1	391	* [[BuildingInIdea]]
66.1	392
	393	= Creating a Build for your own Modules =
	394
	395	== Generating a XAR ==
	396
67.1	397	Follow these steps:
73.2	398
66.1	399	* Put the XWiki XML files into the ##src/main/resources## directory
	400	* Use the ##xar## packaging in the your ##pom.xml##.
	401	* Make sure the XAR packaging extension is registered in Maven.
	402
	403	For example:
66.2	404
66.1	405	{{code language="xml"}}
	406	<project...>
	407	...
	408	<packaging>xar</packaging>
	409	...
	410	<build>
	411	<extensions>
	412	<!-- Needed to add support for the "xar" packaging -->
	413	<extension>
	414	<groupId>org.xwiki.commons</groupId>
	415	<artifactId>xwiki-commons-tool-xar-handlers</artifactId>
	416	<version>(version to use)</version>
	417	</extension>
	418	</extensions>
	419	</build>
	420	...
	421	</project>
	422	{{/code}}
	423
73.2	424	Make sure you run ##mvn xar:format## to ensure your XWiki XML files are properly formatted, following [[XWiki XML files best practices>>XWikiXMLFilesCodeStyle]].
78.1	425
	426	= Building a patched version =
	427
128.2	428	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.
132.1	429
149.1	430	= Develocity Cache =
132.1	431
161.1	432	To speed up the XWiki Maven builds (either on the dev machines or on the CI), we use a [[Develocity Cache>>https://docs.gradle.com/enterprise/tutorials/caching/]].
132.1	433
	434	This is the setup for XWiki:
133.1	435
161.1	436	* In each Commons, Rendering, and Platform source repos, inside ##.mvn## there are 3 files:
149.1	437	** ##extensions.xml##: Declares the Develocity extensions to Maven
	438	** ##develocity.xml##: Configuration for Develocity
	439	** ##develocity-custom-user-data.groovy##: Custom configuration for Develocity to set the Maven profiles as ge.xwiki.org tags
132.1	440	* 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
149.2	441	* On each agent host, there's a ##.m2/.develocity/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/.develocity/keys.properties,destination=/root/.m2/.develocity/keys.properties##)
161.1	442	* 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).
	443
	444	= npm publication =
	445
	446	{{version before="18.0.0RC1"}}
	447	##xwiki-platform## is publishing packages to npm registries during its release process.
	448
	449	##npm## and other tools of the ecosystem do not have to be installed and are retrieved automatically by the [[maven-frontend-plugin>>https://github.com/eirslett/frontend-maven-plugin]].
	450
	451	npm packages are published automatically during the deploy phase of maven.
	452	The packages are published to:
	453
	454	* https://nexus-snapshots.xwiki.org/repository/npmhosted/ for ##SNAPSHOT## version, with ##SNAPSHOT## being replaced by the timestamp at publication time (e.g., ##18.0.0-SNAPSHOT## is published as 18.0.0-1768914629)
	455	* https://www.npmjs.com/ for final versions, in the [[@xwiki>>https://www.npmjs.com/org/xwiki]] group
	456
	457	== Nexus Snapshot npm registries ==
	458
	459	Nexus actually defines three registries
	460
	461	* ##npmproxy##: This is a proxy of the flagship npm registry [[https:~~/~~/registry.npmjs.org/>>https://registry.npmjs.org/]].
	462	* ##npmhosted##: This the only registry where we can publish snapshot versions of our packages.
	463	* ##npm##: This is a virtual registry that merges ##npmproxy## and ##npmhosted##, allowing us to have a single entry point for all the required dependencies required to build xwiki
	464	{{/version}}

Wiki source code of Building XWiki from sources

Quick Links

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected