README - xalan-java - Git at Google


            
            <!--

            
             * Licensed to the Apache Software Foundation (ASF) under one or more

            
             * contributor license agreements. See the NOTICE file distributed with

            
             * this work for additional information regarding copyright ownership.

            
             * The ASF licenses this file to You under the Apache License, Version 2.0

            
             * (the "License"); you may not use this file except in compliance with

            
             * the License. You may obtain a copy of the License at

            
             *

            
             *     http://www.apache.org/licenses/LICENSE-2.0

            
             *

            
             * Unless required by applicable law or agreed to in writing, software

            
             * distributed under the License is distributed on an "AS IS" BASIS,

            
             * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

            
             * See the License for the specific language governing permissions and

            
             * limitations under the License.

            
            -->

            
            Apache Xalan-Java Build, Test, and Release Notes

            
            Copyright 1999-2026 The Apache Software Foundation


            Authors:

            
               Gary Gregory <ggregory@apache.org>

            
               Joe Kesselman <jkesselm@apache.org>

            
               Mukul Gandhi <mukulg@apache.org>


            This document's primarily focused on building artifacts for production

            
            releases of the Apache Xalan-J XSLT processor, but may be helpful for

            
            others working with Xalan's source.


            (0) Prerequisites


            Official Xalan builds are currently being performed using Maven

            
            version 6.3.6 and a Java 1.8 Development Kit. We recommend Eclipse

            
            Temurun for the latter; it is available from

            
            https://adoptium.net/temurin/releases/?version=8. Be sure to install

            
            the JDK, not just the JRE.


            The xalan tests, however, are still relying on Apache Ant. You can

            
            obtain this from https://ant.apache.org/bindownload.cgi. I have been

            
            testing with Ant 1.10.12, but have successfully built with 1.9.16 as

            
            well.


            (1) Steps to build the XalanJ release


            1.1) Obtain the source for XalanJ and its test package.


            "Source Distribution" jarfiles are available which contain a snapshot

            
            of a particular release of the source code; extracting them with "jar

            
            -xf" will yield the xalan-java and xalan-test directories.


            Or (usually preferred) you can use "git clone" to obtain these from

            
            either github.com. or gitbox.apache.org. New development takes place

            
            on the branch currently called "master", which git will fetch by default:


              git clone https://github.com/apache/xalan-java.git

            
              git clone https://github.com/apache/xalan-test.git


            (In the past this code was hosted at gitbox.apache.org, but that now

            
            redirects to the github copy.)


            If you want to build a specific release rather than the development

            
            version, you can obtain that by adding the release's branch name to

            
            the git clone operation. For example, to get the code released as

            
            version 2.7.1, you would issue the command


              git clone https://github.com/apache/xalan-java.git --single-branch --branch xalan-j_2_7_1


            There will also usually be a _maint branch, which is used for development and testing of "hot fixes" that will be made available as new point releases (for example, 2.7.1.1). You would access this as


              git clone https://github.com/apache/xalan-java.git --single-branch --branch xalan-j_2_7_1_maint


            Whether you perform the git clone operations or unpack the source

            
            distribution jarfiles, each produces its own folder: xalan-java and

            
            xalan-test. Since xalan-test looks for code to be tested via the path

            
            ../xalan-java, these will need to be children of the same parent

            
            directory for the tests to run.


            1.2) Set JAVA_HOME and ANT_HOME environment variable. On Linux, assuming

            
            a standard installation of the JDK with the "alternatives" tooling,

            
            the easiest way to be sure you have the right JDK may be to use the

            
            command


              export ANT_HOME=/usr/share/ant

            
              export JAVA_HOME=$(readlink -f /etc/alternatives/java_sdk_1.8.0)


            On Windows, you will probably need to set these more explicitly, and add them to your PATH:


              set ANT_HOME=C:\path\to\your\installed\apache-ant-

            
              set JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-8.0.352.8-hotspot\

            
              set PATH=%JAVA_HOME%;%ANT_HOME%;%PATH%


            1.3) Go to the xalan-java source directory (i.e, from the source

            
            distribution folder, which contains folders "src", "tools" etc), and

            
            from there run the clean-and-distribution-build command:


               On Linux, run ./mvnbuild.sh

            
               On Windows, run ./mvnbuild.bat


            This will build:

            
               ./target/site/apidocs: Javadoc for the Xalan code base


               ./target/site/design: Architecture documentation for Xalan

            
                 (probably outdated)


               ./target/site/xsltc: Architecture documentation for the Xalan bytecode

            
                 compilation operations (probably outdated)


               ./build/*.jar: Executable jarfiles for the XML Serializer, the Xalan

            
                 XSLT Processor, some old xsltc samples and the @xsl.usage taglet

            
                 we used in producing the Javadoc/apidocs (see above).


               ./lib: Xalan dependencies that xalan-test relies on our

            
                 having fetched, copied to where xalan-test can reach them easily.


            (2) Steps to run the XalanJ tests, assuming you have already build

            
            xalan-java as discussed above:


            2.1) Go to the xalan-tests local folder. If you have cloned xalan-java

            
            and xalan-test from Git, it will be a sibling of xalan-java.


            BUT: For XalanJ source distribution users, the xalan-test folder was

            
            shipped as a child of the xalan-java source folder (i.e, parallel to

            
            folders "src", "tools" etc within the main XalanJ codebase folder

            
            location). In theory you *should* be able to run the tests directly

            
            from here, but if you run into trouble try moving xalan-test up to be

            
            a sibling of xalan-java.


            2.2) Ensure the JAVA_HOME, ANT_HOME, and (on Windows) PATH environment

            
            variables have been set as discussed above.


            2.3) Go to the xalan-test folder, and from there run a clean source

            
            build. Unfortunately we don't currently have a single target for this,

            
            so you need to spell out some of the supporting packages:


              Linux: ./build.sh clean jar extensions.classes bugzilla.classes jira.classes

            
              Windows: build clean jar extensions.classes bugzilla.classes jira.classes


            The jar target builds the main XalanJ test driver, testxsl.jar, which

            
            acts as main XalanJ test driver. The .classes targets build supporting

            
            code specific to testing XSLT Extensions or some old issues reported

            
            via Bugzilla or (more recently) Jira.


            2.4) From the xalan-test directory, you can run the necessary XalanJ

            
            tests as follows:


            2.4.1) The most important test set is smoketest. This exercises all

            
            the testcases known to work in Apache Xalan-J, while avoiding some

            
            which have open issues against them.


            Make sure you have built the jar and extensions.classes, as

            
            above. Then, from the xalan-test directory:


              Linux: ./build.sh smoketest

            
              Windows: build smoketest


            At the end of the test run, smoketest should report:


            smoketest-pass:

            
                 [echo]  [minitest] CONGRATULATIONS! The Smoketest passed!


            2.4.2) Run the ant target "apitest", using following command


              Linux: ./build.sh apitest

            
              Windows: build apitest


            At the end of the test run, apitest should report:


            apitest-pass-file-check:

            
                 [echo]  [minitest] CONGRATULATIONS! The api tests passed!


            2.4.3) Run the ant target "conf.xsltc", using the following command


              Linux: ./build.sh conf.xsltc

            
              Windows: build conf.xsltc


            At the end of the test run, conf.xsltc should report:


            [echo]  [minitest] CONGRATULATIONS! The conf.xsltc tests passed!


            PLEASE NOTE that XSLTC has some known issues, which will cause FAIL

            
            reports during this test. These are not considered regressions, and

            
            are specialcased so conf.xsltc reports "passed" despite them. There

            
            are Jira tickets open to address these bugs, and when fixes become

            
            available we will again insist that these tests pass.


               output63         https://issues.apache.org/jira/browse/XALANJ-2642

            
               idkey49          https://issues.apache.org/jira/browse/XALANJ-2640

            
               math111          https://issues.apache.org/jira/browse/XALANJ-2641

            
               whitespace35     https://issues.apache.org/jira/browse/XALANJ-2643


            2.4.4) Other test targets exist, which are either subsets of the above

            
            or are considered less essential for regression testing. You may want

            
            to read through the build.xml file to find them. NOTE that one target,

            
            "api", is currently missing, which causes the "all" target to fail; we

            
            need to clean that up at some point.


            2.5) When bugs are reported, tests should be added (at least to the

            
            jira test set) to demonstrate the problem. When bugs are fixed, those

            
            tests should be migrated either to the appropriate category or to the

            
            "contrib" bucket if they don't fit nicely anywhere else. If the bug report was in error, the test demonstrating the

            
            (correct but unexpected) behavior may be either discarded, or moved as above if we think it's a useful illustration.


            We use JProfiler (https://www.ej-technologies.com/jprofiler) tool for Java software run-time

            
            analysis and optimization of Xalan-J software.
	<!--
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	-->
	Apache Xalan-Java Build, Test, and Release Notes
	Copyright 1999-2026 The Apache Software Foundation

	Authors:
	Gary Gregory <ggregory@apache.org>
	Joe Kesselman <jkesselm@apache.org>
	Mukul Gandhi <mukulg@apache.org>

	This document's primarily focused on building artifacts for production
	releases of the Apache Xalan-J XSLT processor, but may be helpful for
	others working with Xalan's source.

	(0) Prerequisites

	Official Xalan builds are currently being performed using Maven
	version 6.3.6 and a Java 1.8 Development Kit. We recommend Eclipse
	Temurun for the latter; it is available from
	https://adoptium.net/temurin/releases/?version=8. Be sure to install
	the JDK, not just the JRE.

	The xalan tests, however, are still relying on Apache Ant. You can
	obtain this from https://ant.apache.org/bindownload.cgi. I have been
	testing with Ant 1.10.12, but have successfully built with 1.9.16 as
	well.


	(1) Steps to build the XalanJ release

	1.1) Obtain the source for XalanJ and its test package.

	"Source Distribution" jarfiles are available which contain a snapshot
	of a particular release of the source code; extracting them with "jar
	-xf" will yield the xalan-java and xalan-test directories.

	Or (usually preferred) you can use "git clone" to obtain these from
	either github.com. or gitbox.apache.org. New development takes place
	on the branch currently called "master", which git will fetch by default:

	git clone https://github.com/apache/xalan-java.git
	git clone https://github.com/apache/xalan-test.git

	(In the past this code was hosted at gitbox.apache.org, but that now
	redirects to the github copy.)

	If you want to build a specific release rather than the development
	version, you can obtain that by adding the release's branch name to
	the git clone operation. For example, to get the code released as
	version 2.7.1, you would issue the command

	git clone https://github.com/apache/xalan-java.git --single-branch --branch xalan-j_2_7_1

	There will also usually be a _maint branch, which is used for development and testing of "hot fixes" that will be made available as new point releases (for example, 2.7.1.1). You would access this as

	git clone https://github.com/apache/xalan-java.git --single-branch --branch xalan-j_2_7_1_maint

	Whether you perform the git clone operations or unpack the source
	distribution jarfiles, each produces its own folder: xalan-java and
	xalan-test. Since xalan-test looks for code to be tested via the path
	../xalan-java, these will need to be children of the same parent
	directory for the tests to run.


	1.2) Set JAVA_HOME and ANT_HOME environment variable. On Linux, assuming
	a standard installation of the JDK with the "alternatives" tooling,
	the easiest way to be sure you have the right JDK may be to use the
	command

	export ANT_HOME=/usr/share/ant
	export JAVA_HOME=$(readlink -f /etc/alternatives/java_sdk_1.8.0)

	On Windows, you will probably need to set these more explicitly, and add them to your PATH:

	set ANT_HOME=C:\path\to\your\installed\apache-ant-
	set JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-8.0.352.8-hotspot\
	set PATH=%JAVA_HOME%;%ANT_HOME%;%PATH%


	1.3) Go to the xalan-java source directory (i.e, from the source
	distribution folder, which contains folders "src", "tools" etc), and
	from there run the clean-and-distribution-build command:

	On Linux, run ./mvnbuild.sh
	On Windows, run ./mvnbuild.bat

	This will build:
	./target/site/apidocs: Javadoc for the Xalan code base

	./target/site/design: Architecture documentation for Xalan
	(probably outdated)

	./target/site/xsltc: Architecture documentation for the Xalan bytecode
	compilation operations (probably outdated)

	./build/*.jar: Executable jarfiles for the XML Serializer, the Xalan
	XSLT Processor, some old xsltc samples and the @xsl.usage taglet
	we used in producing the Javadoc/apidocs (see above).

	./lib: Xalan dependencies that xalan-test relies on our
	having fetched, copied to where xalan-test can reach them easily.

	(2) Steps to run the XalanJ tests, assuming you have already build
	xalan-java as discussed above:

	2.1) Go to the xalan-tests local folder. If you have cloned xalan-java
	and xalan-test from Git, it will be a sibling of xalan-java.

	BUT: For XalanJ source distribution users, the xalan-test folder was
	shipped as a child of the xalan-java source folder (i.e, parallel to
	folders "src", "tools" etc within the main XalanJ codebase folder
	location). In theory you should be able to run the tests directly
	from here, but if you run into trouble try moving xalan-test up to be
	a sibling of xalan-java.

	2.2) Ensure the JAVA_HOME, ANT_HOME, and (on Windows) PATH environment
	variables have been set as discussed above.

	2.3) Go to the xalan-test folder, and from there run a clean source
	build. Unfortunately we don't currently have a single target for this,
	so you need to spell out some of the supporting packages:

	Linux: ./build.sh clean jar extensions.classes bugzilla.classes jira.classes
	Windows: build clean jar extensions.classes bugzilla.classes jira.classes

	The jar target builds the main XalanJ test driver, testxsl.jar, which
	acts as main XalanJ test driver. The .classes targets build supporting
	code specific to testing XSLT Extensions or some old issues reported
	via Bugzilla or (more recently) Jira.


	2.4) From the xalan-test directory, you can run the necessary XalanJ
	tests as follows:

	2.4.1) The most important test set is smoketest. This exercises all
	the testcases known to work in Apache Xalan-J, while avoiding some
	which have open issues against them.

	Make sure you have built the jar and extensions.classes, as
	above. Then, from the xalan-test directory:

	Linux: ./build.sh smoketest
	Windows: build smoketest

	At the end of the test run, smoketest should report:

	smoketest-pass:
	[echo] [minitest] CONGRATULATIONS! The Smoketest passed!


	2.4.2) Run the ant target "apitest", using following command

	Linux: ./build.sh apitest
	Windows: build apitest

	At the end of the test run, apitest should report:

	apitest-pass-file-check:
	[echo] [minitest] CONGRATULATIONS! The api tests passed!


	2.4.3) Run the ant target "conf.xsltc", using the following command

	Linux: ./build.sh conf.xsltc
	Windows: build conf.xsltc

	At the end of the test run, conf.xsltc should report:

	[echo] [minitest] CONGRATULATIONS! The conf.xsltc tests passed!

	PLEASE NOTE that XSLTC has some known issues, which will cause FAIL
	reports during this test. These are not considered regressions, and
	are specialcased so conf.xsltc reports "passed" despite them. There
	are Jira tickets open to address these bugs, and when fixes become
	available we will again insist that these tests pass.

	output63 https://issues.apache.org/jira/browse/XALANJ-2642
	idkey49 https://issues.apache.org/jira/browse/XALANJ-2640
	math111 https://issues.apache.org/jira/browse/XALANJ-2641
	whitespace35 https://issues.apache.org/jira/browse/XALANJ-2643

	2.4.4) Other test targets exist, which are either subsets of the above
	or are considered less essential for regression testing. You may want
	to read through the build.xml file to find them. NOTE that one target,
	"api", is currently missing, which causes the "all" target to fail; we
	need to clean that up at some point.

	2.5) When bugs are reported, tests should be added (at least to the
	jira test set) to demonstrate the problem. When bugs are fixed, those
	tests should be migrated either to the appropriate category or to the
	"contrib" bucket if they don't fit nicely anywhere else. If the bug report was in error, the test demonstrating the
	(correct but unexpected) behavior may be either discarded, or moved as above if we think it's a useful illustration.

	We use JProfiler (https://www.ej-technologies.com/jprofiler) tool for Java software run-time
	analysis and optimization of Xalan-J software.