Building

This document currently details Maven commands for building Azure SDK For Java.

JDK 8 vs JDK 11

The build system is configured to support JDK, as well as the current long-term support version of the JDK (currently JDK 11). The commands presented below will work on both JDKs.

pom.client.xml vs pom.data.xml

This repository contains two pom files for client libraries. pom.client.xml is the pom file for the newer, more modern client libraries, whereas pom.data.xml is the pom file for the previous generation of client libraries. The commands below all use pom.client.xml, as this document focuses on these client libraries. For client libraries that are from the previous generation, please refer to the relevant documentation for them.

Installing the build tools

A lot of the commands that follow will depend on the availability of the build tooling. This can be installed by running the following:

mvn install -f eng/code-quality-reports/pom.xml 

Testing for SpotBugs and CheckStyle issues

SpotBugs and CheckStyle are configured to break the build if there is any issues discovered by them. It is therefore strongly recommended to run the following maven goals locally before submitting a pull request:

mvn spotbugs:check checkstyle:checkstyle-aggregate -f pom.client.xml -DskipTests -Dgpg.skip

Testing for breaking API changes

The build is configured with Revapi to check builds against the latest GA release in Maven. At present the build is not configured to fail, but very soon it will be configured to fail the build when a breaking change is detected. To check for breaking changes, run the following:

mvn revapi:check -f pom.client.xml

Skipping analysis for local build

The default mvn build/install command execute the code quality tools that runs analysis for check-style violations, breaking changes etc.. This step add more time. For intermediate build/install during development, these analysis can be skipped by adding following mvn options

-Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotbugs.skip=true -Drevapi.skip=true

-Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotbugs.skip=true -Drevapi.skip=true

Generating HTML reports

To generate HTML reports for 'Maven Site', as well as aggregate CheckStyle, SpotBugs, Jacoco, Revapi, and JavaDoc reports, you need to run the following commands:

Spotbugs, checkstyles, Revapi, and Javadocs

mvn install site:site site:stage -f pom.client.xml -Dgpg.skip 

JaCoCo test coverage

mvn test -f pom.client.xml -Dgpg.skip -Dinclude-non-shipping-modules

Once this completes, the generated reports are available in the following locations:

Tool	Output Location
SpotBugs	/eng/spotbugs-aggregate-report/target/spotbugs/spotbugsXml.html
CheckStyle	/target/staging/checkstyle-aggregate.html
JavaDoc	/target/staging/apidocs/index.html
Revapi	/target/staging/revapi-aggregate-report.html
Maven Site	/target/staging/index.html
JaCoCo	/eng/jacoco-test-coverage/target/site/test-coverage/index.html

Code snippets in README

Samples in all README.md files should use compilable code to ensure they are updated when source code is updated. To do so, we use a utility tool to embed source code from Java files into README markdown files. Steps to add code snippets in README using the tool:

• Download and install NodeJS
• Create ReadmeSamples.java file in src/samples/java/ for which README.md should be updated
• Add all the code snippets in the above Java file that should be included in README.md
• Now, in README.md, add the embedme tag as shown below (the sample shows inserting code from line number 10 to 20)

<!-- embedme path/to/ReadmeSamples.java#L10-L20 -->
```java
```

• To embed code using the tool, run the following command

npx embedme path/to/README.md

• Verify the README.md file to confirm the samples are inserted as expected