forked from Azure/azure-sdk-for-java
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added azure cosmos setup guide (Azure#32650)
* Added azure cosmos setup guide * Update setup.md * Added cosmos emulator link and parameters * Removed noexplorer and noui params * Update setup.md Co-authored-by: Fabian Meiswinkel <[email protected]>
- Loading branch information
1 parent
a8bdaac
commit e361ba3
Showing
1 changed file
with
101 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| This document currently details Maven commands for building Azure Cosmos SDK. | ||
|
|
||
| ### Fork and clone the repository | ||
| To build and develop locally, it is strongly recommended to fork and clone the repository: https://github.com/Azure/azure-sdk-for-java | ||
|
|
||
| <u>**NOTE:**</u> If running on Windows please ensure that you have enabled LFS-support in Git - see the installation instructions [here](https://git-lfs.com/). | ||
|
|
||
| **<u>NOTE:</u>** All of the below commands need to be run from home directory of azure-sdk-for-java repository. | ||
|
|
||
| ### 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 | ||
| Building azure-cosmos SDK locally depends on the availability of the build tooling. This can be installed by running the following: | ||
|
|
||
| ```shell | ||
| mvn install -f eng/code-quality-reports/pom.xml | ||
| ``` | ||
|
|
||
| ### Building and Testing | ||
|
|
||
| To build azure-cosmos library using maven command line, run the following command | ||
|
|
||
| ```shell | ||
| mvn -e -Dgpg.skip -DskipTests -Dmaven.javadoc.skip=true -Dcodesnippet.skip=true -Dspotbugs.skip=true -Dcheckstyle.skip=true -Drevapi.skip=true -pl com.azure:azure-cosmos -am clean verify | ||
| ``` | ||
|
|
||
| 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 "--%"](https://technet.microsoft.com/library/hh847892.aspx) | ||
|
|
||
| ```shell | ||
| mvn --% -e -Dgpg.skip -DskipTests -Dmaven.javadoc.skip=true -Dcodesnippet.skip=true -Dspotbugs.skip=true -Dcheckstyle.skip=true -Drevapi.skip=true -pl com.azure:azure-cosmos -am clean verify | ||
| ``` | ||
|
|
||
| To run unit tests, simply remove `-DskipTests` option from above commands. | ||
|
|
||
| ### Testing for SpotBugs, CheckStyle, and JavaDoc issues | ||
| SpotBugs, CheckStyle, and JavaDoc plugins are configured to break the build if there are any issues discovered by them. It is therefore strongly recommended to run the following maven options locally before submitting a pull request: | ||
|
|
||
| ```shell | ||
| -Dmaven.javadoc.skip=true -Dcheckstyle.skip=true -Dspotbugs.skip=true | ||
| ``` | ||
|
|
||
| ### Testing for breaking API changes | ||
| The build is configured with [Revapi](https://revapi.org) plugin to check builds against the latest GA release in Maven. Build will fail when a breaking change is detected. To check for breaking changes, run the following maven options locally before submitting a pull request: | ||
|
|
||
| ```shell | ||
| -Drevapi.skip=true | ||
| ``` | ||
|
|
||
| ### 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 -Dcodesnippet.skip=true | ||
| ``` | ||
|
|
||
| Note: It is strongly recommended to run the analysis locally before submitting a pull request. | ||
|
|
||
| ### Setting IntelliJ IDE for Java SDK | ||
|
|
||
| Open azure-sdk-for-java/sdk/cosmos/azure-cosmos/pom.xml in IntelliJ IDE as project to import it as a maven project: | ||
|  | ||
|
|
||
|
|
||
| ### Defining Project Structure | ||
|
|
||
| Open project structure through project settings for azure-cosmos project and set the SDK and Language Level to JDK 11 under Project tab: | ||
|  | ||
|
|
||
| Open Modules tab in the same settings and set the Language level to match project default, which should be JDK 11: | ||
|  | ||
|
|
||
|
|
||
| Set target bytecode version for the project azure-cosmos in IntelliJ Preferences for Java Compiler as JDK 11: | ||
|  | ||
|
|
||
| ### Installing the Cosmos DB emulator | ||
|
|
||
| Setup Azure Cosmos DB Emulator by following [this instruction](https://docs.microsoft.com/azure/cosmos-db/local-emulator). Then please export the emulator's SSL certificates and install them in the JVM trust stores on your development machine following [this instruction](https://learn.microsoft.com/azure/cosmos-db/local-emulator-export-ssl-certificates). | ||
|
|
||
| ### Running Unit Tests | ||
|
|
||
| Unit tests are tests with group "unit" and can be run from IntelliJ directly without needing any Azure Cosmos DB Account or Emulator support. To run them, right click on any unit test class and run them. To test this, run `ClientConfigDiagnosticsTest` from IntelliJ IDE directly. | ||
|
|
||
| ### Running Integration Tests | ||
|
|
||
| Azure Cosmos Java SDK has different Integration tests which can be run with Azure Cosmos Emulator or Azure Cosmos DB production Account. | ||
|
|
||
| Emulator Integration tests are with test group `emulator`, labeled in the code as `groups = { "emulator" }` and can be run from IntelliJ after starting Azure Cosmos DB Emulator on the local development machine. For example, `DocumentCrudTest` is of group emulator. | ||
|
|
||
| Latest version of Azure Cosmos DB Emulator can be downloaded and installed from [here](https://learn.microsoft.com/azure/cosmos-db/local-emulator) | ||
| Our CI pipelines start Azure Cosmos DB Emulator with these parameters. It is highly recommended to use these for local development and testing. | ||
| ```shell | ||
| /enablepreview /EnableSqlComputeEndpoint /disableratelimiting /enableaadauthentication /partitioncount=50 /consistency=Strong | ||
| ``` | ||
|
|
||
| Other test groups are meant to be tested against Azure Cosmos DB production account, but can also be tested against Emulator. There are multiple different test groups like `groups = {"simple", "long", "direct", "multi-region", "multi-master"}`. For example, `CosmosItemTest` is a simple group test which can be run against Azure Cosmos DB production account, as well as against emulator. | ||
|
|
||
| To run any test against Azure Cosmos DB production account, it is required to update `TestConfigurations.java` class with account host and key. | ||
| NOTE: When creating a PR, make sure to remove any account key and account host information from the PR. To avoid security breaches, never commit and push any keys and host information related to Azure Cosmos DB Account. |