EchoSVG

EchoSVG is a fork of Apache Batik, a Java based toolkit for applications which handle images in the Scalable Vector Graphics (SVG) format for various purposes, such as viewing, generation or manipulation.

Thanks to its usage of the CSS4J style parser, supports level 4 CSS selectors and color values (including colors with alpha channel) as well as the Level 5 color-mix() function.

This document mostly contains information of interest to developers, like how to build from source or run tests. If you want general information (like how to use the binaries) you are invited to read the Wiki, especially the part about why this fork was created.

If you are using Apache Batik you may want to read how Batik's testing infrastructure was improved, and if you decide to switch to EchoSVG, the MIGRATING_FROM_BATIK document may be of help.

Building from source

Requirements

To build EchoSVG you need the following software installed:

• The Git version control system is required to obtain the sources. Any recent version should suffice.

• Java version 11 to 21 (later versions may work but aren't tested by CI). You can install it from your favourite package manager or by downloading from Adoptium.

Building with Gradle

Execute the build script with gradlew build to build. For example:

git clone https://github.com/css4j/echosvg.git
cd echosvg
./gradlew build

Tests

Most of the (JUnit-based) test suite is executed during build (except some tests that are currently incompatible with Gradle), but beware that some tests are platform-dependent and could fail. If you encounter test failures, please open an issue with the details so the necessary tweaks can be made. If the failing test involves an image comparison, you may want to read IMAGE_COMPARISONS.

To build without running the tests:

./gradlew build -x check

In the past, the full test suite could be executed from the Eclipse IDE, but that is not the case anymore. Tests run satisfactorily from IntelliJ IDEA, except for the security tests (that do not run on Gradle either, see #19); please open an issue if you find problems executing the tests from other IDEs.

Note: when running tests from the Eclipse IDE, it is recommended to run them as a "JUnit Test" in the "Run As" menu option. If you run them as "Gradle Test" you may encounter well-known security-related issues (issue #19).

Interactive tests

Several interactive tests can be executed via:

./gradlew iTest

Note that several of those tests are failing (a few being unfinished).

Code coverage

Generate a JaCoCo code coverage report with:

./gradlew testCodeCoverageReport

The XML and HTML reports can be found under the echosvg-all/build/reports/jacoco/testCodeCoverageReport directory, with the index file for the HTML report being at

echosvg-all/build/reports/jacoco/testCodeCoverageReport/html/index.html

Pull Requests aimed to increase the code coverage would be welcome.

Benchmarks

This project uses JMH for benchmarking. To run all the benchmarks (currently only one):

./gradlew runJmh

To run specific benchmark(s) matched by a regular expression:

./gradlew runJmh <regexp>

A jmh-ready fat Jar with all the dependencies is available at echosvg-test/build/libs/echosvg-<version>-jmh.jar, and is the recommended way to run benchmarks:

java -jar echosvg-test/build/libs/echosvg-<version>-jmh.jar <regexp>

Deploying to a Maven repository

Use:

• ./gradlew publishToMavenLocal to install in your local Maven repository.

• ./gradlew publish to deploy to a (generally remote) Maven repository.

If you plan to deploy to a repository, please configure the mavenReleaseRepoUrl and/or mavenSnapshotRepoUrl properties (for example in GRADLE_USER_HOME/gradle.properties or in the command line). Otherwise, Gradle shall create a build/repository subdirectory and deploy there.

Properties mavenRepoUsername and mavenRepoPassword can also be set (generally from the command line).

If you would rather look directly at the Gradle publish configurations, please read the publishing.repositories.maven block of echosvg.java-conventions.gradle.

Creating a uber Jar or fat Jar

Sometimes, in non-modular projects it is useful to have a single Jar file bundled with all the dependencies, often called a uber Jar or fat Jar. Execute the uberjar task to create one with all the EchoSVG modules:

./gradlew uberjar

The file is to be found at echosvg-all/build/libs/echosvg-all-<version>-alldeps.jar.

However, that archive is big and you may only want the classes that are needed to run a specific module. In that case, run:

./gradlew <subproject-name>-jar-with-deps

and the archive shall be available at <subproject-name>/build/libs/<subproject-name>-<version>-with-deps.jar.

For example, to create an all-deps jar for echosvg-svggen:

./gradlew echosvg-svggen-jar-with-deps

and the it will be located at echosvg-svggen/build/libs/echosvg-svggen-<version>-with-deps.jar.

Note that if you execute

./gradlew echosvg-all-jar-with-deps

the resulting jar will be identical to echosvg-all-<version>-alldeps.jar.

Produce a modular Javadoc

A Javadoc of all the modules is produced by the modularJavadoc task:

./gradlew modularJavadoc

The Javadocs are created at echosvg-all/build/docs/modular.

Produce a non-modular Javadoc

If you do not like modular javadocs, a merged non-modular Javadoc can be built with the mergedJavadoc task:

./gradlew mergedJavadoc

The Javadocs are created at echosvg-all/build/docs/javadoc.

This task may be removed in the future; if the non-modular javadocs are useful to you, please open an issue so it is preserved.

Other common tasks

OWASP Dependency Check

Check for known vulnerable dependencies that are used in the build.

./gradlew dependencyCheckAnalyze

Dependency Licensing

Generate a report about the licenses of the dependencies:

./gradlew generateLicenseReport

Check that the licenses of all the dependencies are allowed, fail otherwise:

./gradlew checkLicense

(the above task is executed on each build)

Open the project in your IDE

Modern IDEs are able to import Gradle projects and let it manage the dependencies. In IntelliJ IDEA you can just open the root directory and the Gradle project is opened, while in the Eclipse IDE you need to import it explicitly:

File > Import... > Gradle > Existing Gradle Project

Eclipse shall ask you if you want to use a wrapper or its own instance of Gradle, select the "wrapper" choice.

In Eclipse, it is advisable to run a build with ./gradlew build before importing the project. Apparently Eclipse requires some files produced by a build but is unable to do that by itself.

Note: it is normal to experience build issues with the echosvg-test-scripts subproject in Eclipse, you may prefer to keep that project closed.

Usage from a Gradle project

If your Gradle project depends on echosvg, you can use this project's own Maven repository in a repositories section of your build file:

repositories {
    maven {
        url "https://css4j.github.io/maven/"
        mavenContent {
            releasesOnly()
        }
        content {
            includeGroupByRegex 'io\\.sf\\..*'

            // Alternative to the regex:
            //includeGroup 'io.sf.carte'
            //includeGroup 'io.sf.jclf'
            //includeGroup 'io.sf.graphics'
            //includeGroup 'io.sf.w3'
        }
    }
}

please use that repository only for the artifact groups that it supplies (basically those listed in the above includeGroup statements).

Then, in your build.gradle file you can list the dependencies, for example:

dependencies {
    implementation "io.sf.carte:echosvg-transcoder:${echosvgVersion}"
}

or, if you want all of the main modules:

dependencies {
    implementation "io.sf.carte:echosvg-all:${echosvgVersion}"
}

where echosvgVersion would be defined in a gradle.properties file (current version is 1.2.3).

Licensing

For licensing issues, please read the LICENSE and NOTICE files. The tests use files which may have their own additional licenses, under the samples directory. Please look for the appropriate license files there.