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.

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 

Building and Testing

To build all the libraries, run the following command

mvn install -f pom.xml -Dcheckstyle.skip -Dgpg.skip -Dmaven.javadoc.skip -Drevapi.skip -DskipSpringITs -DskipTests -Dspotbugs.skip -Djacoco.skip

Tips: if you're using powershell on windows, you may run into this error[ERROR] Unknown lifecycle phase ".skip". You must specify a valid lifecycle phase or a goal in the format, this can be fixed by telling powershell to stop parsing this command with stop-parsing parameter "--%"

mvn --% install -f pom.xml -Dcheckstyle.skip -Dgpg.skip -Dmaven.javadoc.skip -Drevapi.skip -DskipSpringITs -DskipTests -Dspotbugs.skip -Djacoco.skip

To build the new wave of track 2 libraries only, run the following command

mvn install -f pom.xml -Dgpg.skip -Drevapi.skip -DskipTests -pl com.azure:jacoco-test-coverage -am

To build the libraries for a specific service, run the following command

mvn install -f sdk/<servicename>/pom.xml  -Dgpg.skip -Drevapi.skip -DskipTests

For example, to build appconfiguration client library run the following command

mvn install -f sdk/appconfiguration/pom.xml -Dgpg.skip -Drevapi.skip -DskipTests

To run unit tests, simply remove -DskipTests option from above commands.

Testing for SpotBugs and CheckStyle issues

SpotBugs and CheckStyle are configured to break the build if there are 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 -DskipTests -Dgpg.skip -pl "package-id:artifact-id" -am

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

Skipping analysis for local build

The default mvn build/install command executes the code quality tools that run analysis for check-style violations, bugs and breaking changes. The build takes more time to complete with these analyses enabled. For intermediate build/install during local development, they can be skipped by adding the following mvn options:

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

Note: It is strongly recommended to run the analysis locally before submitting a pull request.

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 -Dgpg.skip 

JaCoCo test coverage

mvn test -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 compliable code to ensure they are updated when the 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. See How to define a codesnippet reference.

• Now, in README.md, add the codesnippet reference. See How to inject codesnippet into READMEs.

• Rebuild the package will embed code automatically,

mvn clean install {path/to/client}/pom.xml 

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