# Release Notes ## SpecDiff ## Version 3.0 ## TBD

[Skip TOC]

## Table of Contents

Introduction
New in This Release
System Requirements
Release Contents
Installation
Using SpecDiff
Known Bugs and Issues

## Introduction

These release notes contain information about version 3.0 of the SpecDiff utility. See the SpecDiff 3.0 project page for more information about SpecDiff.

SpecDiff is a Java command-line tool which provides an easy way to compare two document trees and build a full HTML diff report. SpecDiff is a replacement for BlenderRev, and provides a full three-way diff view of Java APIs over a tree of JavaDocs.

## New in this Release

Bug ID | Description
--- | ---
b11: Support for JDK 14-specific features, important fixes
JCK-7312406 | Empty field/method/constructor details
JCK-7311889 | Specdiff 3.0 no longer works with latest jdk-dev javadoc
JCK-7311738 | Exception while running specdiff with Include option
JCK-7311267 | Specdiff doesn't work with module layout.
JCK-7308893 | Specdiff options needs to be enchanced as per JEP 293
JCK-7308812 | Specdiff update for proposed change in javadoc HTML5 mode
JCK-7308800 | java.nio.file.NoSuchFileException generated from specdiff 3.0
b07: Support for JDK 9-specific features, important fixes
JCK-7307018 | Adapt specdiff to the recent changes in module documentation
JCK-7306980 | specdiff apidiffs/*.html files should contain Oracle copyright
b06: Important fixes
JCK-7306609 | specdiff needs to replace regexp with java.util.regex
| A number of minor fixes and improvements.
b05: Support for JDK 9-specific features, important fixes
JCK-7304091 | SpecDiff needs to account for Module info in JavaDoc for JDK 9
JCK-7301963 | Numerous parser warnings since JDK7b40
b04: Important fixes, HTML 5 support for generic HTML/docbook mode (partial fix)
JCK-7305023 | SpecTrac/SpecDiff merge procedure does not handle (even minor) inconsistencies in .spec files properly
JCK-7301155 | Specdiff does not copy images
JCK-7300499 | Non-html files are not getting to the project
JCK-7305656 | specdiff crashes when comparing JDK9b93 v.s. JDK9b94
JCK-7304314 | SpecDiff should handle HTML 5 tags in context compilation in generic HTML/docbook mode (partial fix)
b03: Appears inconsistent due to some reason
b02: HTML 5 support for "javadoc" mode
JCK-7304312 | SpecDiff should handle HTML 5 tags in context compilation in "javadoc" mode
JCK-7304316 | Create sample documents & unit tests for JCK-7304312
b01: Important fixes
JCK-7305045 | SpecTrac/SpecDiff does not close files (streams/writters/channels) properly
JCK-7305086 | 10..20% of SpecDiff unit/functional tests fail on Windows

[Top]

## System Requirements

Using SpecDiff 3.0 requires a properly configured, certified Java Platform, Standard Edition (Java SE™ platform) runtime environment version 7.0 or later.

## Installation

No installation or configuration is required, it's ready to run from an installation folder.

## Release Contents

This section lists the components under the base subdirectory structure (`SpecDiff-3.0/`) that is created when you unzip the SpecDiff distribution archive during installation.

### Component Descriptions and Locations

Component | Description
--- | ---
`README.html` | The SpecDiff release notes (this document).
`specdiff.jar` | The main class archive that is necessary to run SpecDiff
`lib/` | The folder with libraries (JAR(s)) that are necessary to run SpecDiff
`javadoc/` | Contains SpecDiff API JavaDoc

## Using SpecDiff

SpecDiff has the following synopsis:

    java -jar ${SPECDIFFHOME}/specdiff.jar <oldHTML> <newHTML>
       [--out=<dirname>]
       [--verbose]
       [--hu | --hideUnchanged]
       [--i | --includes=<pattern>]
       [--e | --excludes=<pattern>]
       [--crn | --crn="<custom-copyright-notice>"]
       [--config="javadoc" | "plain" | <filename>]

oldHTML

Defines the path to an old document tree, or the path/URL to a single file.

newHTML

Defines the path to an new document tree, or the path/URL to a single file.

--out=dirname

The location where the SpecDiff report will be generated.

--hu | --hideUnchanged

Hide the unchanged packages/classes/methods

--v|--verbose

More output to print

--i | --includes=patterns

Ant-like pattern to include files/folders

--e | --excludes=patterns

Ant-like pattern to exclude files/folders

--crn | --crn="<custom-copyright-notice>"

If this option is specified, each HTML page generated by specdiff includes copyright notice at the bottom of the page. Default copyright notice looks like:
© $YEAR Oracle Corporation and/or its affiliates
where $YEAR corresponds to the year in which the diffs were generated.
Custom copyright notice may be provided as a quoted text. The custom copyright notice is inserted into generated HTML "as is", so the quoted text must be escaped properly - e.g. © character must be escaped as `&copy;` etc.

--config=<spec-format> Defines format of specification, may be on of:

The SpecDiff profile name or path to profile file

- javadoc -- JavaDoc-generated Java API specification(default)
- jls -- JLS specification derived from docbook
- jvms -- JVMS specification derived from docbook
- plain -- generic HTML specification
- <filename> -- Path to the profile file (for advanced users)

### Usage Examples

This section contains simple examples that show how to start the SpecDiff tool from the command line. See System Requirements for initial setup.

Example 1: To report differences in API documentation for java.math and java.util packages (with subpackages) between two JDK builds.

    > java -jar specdiff.jar /jdk7/b101/docs/api /jdk7/b102/docs/api \
          --i="java/math/**,java/util/**" --out=/tmp/specdiff

Example 2: To compare a single JavaDoc file stored locally with previous version pointed by URL

    > java -jar specdiff.jar \
          http://download.oracle.com/javase/7/docs/api/java/lang/Byte.html \
          /jdk8/docs/api/java/lang/Byte.html

Example 3: To compare two sets of HTML specifications stored not in JavaDoc format

    > java -jar specdiff.jar ver1/ ver2/ --config=plain

### Operating Modes

There are no operating modes.

[Top]

## Known Bugs and Issues

Please visit bugs.openjdk.java.net (Project - JCK, component - tck-tools, subcomponent - specdiff) to see list of known SpecDiff issues.

If you find any issues, please report them to the SPECTRAC_DEV_WW_GRP@oracle.com alias, or on bugs.openjdk.java.net.

Copyright © 2008, 2015, Oracle and/or its affiliates. All rights reserved.