<!-- * 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-2023 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.