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

Copyright 1999-2023 The Apache Software Foundation

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

This file primarily, contains instructions to the person(s) who shall be making an Apache XalanJ 
release for distribution, along with the instructions about how to test XalanJ release before 
recommending the release for distribution.

The details mentioned within this file, may also be used, by XalanJ source distribution users to 
build and test XalanJ from the source distribution (except that, "git clone" steps as mentioned 
within this file, might not be required to be run by XalanJ source distribution users).

(1) Steps to build the XalanJ release

1) Do a git clone, of the relevant XalanJ branches:

git clone --single-branch https://gitbox.apache.org/repos/asf/xalan-java.git -b xalan-j_2_7_1_maint

git clone https://gitbox.apache.org/repos/asf/xalan-test.git

This creates two folders: xalan-java and xalan-test. These folders need to be parallel to
each other, to be able to follow the XalanJ build and tests steps as described in this document,
for making a XalanJ release for distribution.

2) Set JAVA_HOME and ANT_HOME environment variables, for example on Windows:

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

set ANT_HOME=C:\java\apache-ant-1.10.12

3) Run the command, "build clean fulldist" from folder xalan-java.

For XalanJ source distribution users, this command needs to be run from, the root 
of the XalanJ source distribution folder (i.e, from the source distribution folder, 
which contains folders "src", "tools" etc).

(2) Steps to run the XalanJ tests, on XalanJ implementation

Note that, for XalanJ source distribution users, XalanJ implementation shall be 
produced (that XalanJ source distribution users, might want to test) by running 
the build command "build clean fulldist" from the root of the XalanJ source 
distribution folder.

1) Go to the XalanJ tests repos's, local git clone folder:
cd ..\xalan-test

For XalanJ source distribution users, xalan-test folder is located at the root of the XalanJ 
source distribution folder (i.e, parallel to folders "src", "tools" etc within the main XalanJ 
codebase folder location), from where XalanJ source distribution users may run XalanJ 
tests, by using the "build" script located at this folder location.

2) Set JAVA_HOME and ANT_HOME environment variables, for example:

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

set ANT_HOME=C:\java\apache-ant-1.10.12

3) Run the command "build clean jar" from folder xalan-test. This produces
the file testxsl.jar that acts as main XalanJ test driver, within folder xalan-test/java/build.

4) Run the necessary XalanJ tests as follows,

The tests described below within points 4.1, 4.2, 4.3 need to be run from folder xalan-test. 

4.1 Run the ant target "smoketest", using following two commands in sequence shown below

build extensions.classes

build smoketest

The final result of the command "build smoketest" should be following,

smoketest-pass:
     [echo]  [minitest] CONGRATULATIONS! The Smoketest passed!
     
4.2 Run the ant target "apitest", using following command

build apitest

The final result of the command "build apitest" should be following,

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

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

build conf.xsltc

The final result of the command "build conf.xsltc" should be following,

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

The XalanJ XSLTC processor, producing compiled translets, is known to have certain issues 
as summarized by the following jira tickets, for the respective mentioned XalanJ conf.xsltc 
test cases as mentioned below (users shall currently see, these xalanj test cases as failing, 
within the test build conf.xsltc's output).

1) output63         https://issues.apache.org/jira/browse/XALANJ-2642
2) idkey49          https://issues.apache.org/jira/browse/XALANJ-2640
3) math111          https://issues.apache.org/jira/browse/XALANJ-2641
4) whitespace35     https://issues.apache.org/jira/browse/XALANJ-2643

These XSLT transformation issues, do not exist with the XalanJ interpretive processor.