|
3 | 3 | This document will walk you through on what's needed to start contributing code to OpenSearch Benchmark.
|
4 | 4 |
|
5 | 5 | ## Installation
|
| 6 | + |
6 | 7 | ### Prerequisites
|
7 | 8 |
|
8 |
| -- Pyenv : Install `pyenv` and follow the instructions in the output of `pyenv init` to setup your shell and restart it before proceeding. |
9 |
| -For more details please refer to the [PyEnv installation instructions](https://github.com/pyenv/pyenv#installation). |
10 |
| -- JDK : JDK version required to build OpenSearch. Please refer to the [build setup requirements](https://github.com/opensearch-project/OpenSearch/blob/ca564fd04f5059cf9e3ce8aba442575afb3d99f1/DEVELOPER_GUIDE.md#install-prerequisites). |
11 |
| -- Docker : Docker and additionally `docker-compose` on Linux. |
12 |
| -- Git : git 1.9 or latter. |
| 9 | + - Pyenv : Install `pyenv` and follow the instructions in the output of `pyenv init` to set up your shell and restart it before proceeding. |
| 10 | + For more details please refer to the [PyEnv installation instructions](https://github.com/pyenv/pyenv#installation). |
| 11 | + |
| 12 | + - JDK: Although OSB is a Python application, it optionally builds and provisions OpenSearch clusters. JDK version 17 is used to build the current version of OpenSearch. Please refer to the [build setup requirements](https://github.com/opensearch-project/OpenSearch/blob/ca564fd04f5059cf9e3ce8aba442575afb3d99f1/DEVELOPER_GUIDE.md#install-prerequisites). |
| 13 | + Note that the `javadoc` executable should be available in the JDK installation. An earlier version of the JDK can be used, but not all the integration tests will pass. |
| 14 | + |
| 15 | + ``` |
| 16 | + export JAVA_HOME=/path/to/JDK17 |
| 17 | +
|
| 18 | + ``` |
| 19 | +
|
| 20 | + - Install Docker and `docker-compose`. Start the Docker server. The user running the integration tests should have the permissions required to run docker commands. Test by running `docker ps`. |
| 21 | +
|
| 22 | + - Git : git 1.9 or later. |
13 | 23 |
|
14 | 24 | ### Setup
|
15 | 25 |
|
16 |
| -Use the following command-line instructions to setup OpenSearch Benchmark for development: |
| 26 | +Use the following command-line instructions to set up OpenSearch Benchmark for development: |
17 | 27 | ```
|
18 |
| -git clone https://github.com/opensearch-project/OpenSearch-Benchmark.git |
| 28 | +git clone https://github.com/opensearch-project/OpenSearch-Benchmark |
19 | 29 | cd OpenSearch-Benchmark
|
20 | 30 | make prereq
|
21 | 31 | make install
|
@@ -52,56 +62,29 @@ In order to run tests within the PyCharm IDE, ensure the `Python Integrated Tool
|
52 | 62 |
|
53 | 63 | ## Executing tests
|
54 | 64 |
|
55 |
| -Once setup is complete, you may run unit/integration tests using the following : |
56 |
| - |
57 |
| -``` |
58 |
| -## Run a unit test |
59 |
| -make test |
60 |
| -
|
61 |
| -## Run integration tests |
62 |
| -make it |
63 |
| -``` |
64 |
| - |
65 |
| -### Important information related to integration tests |
| 65 | +Once setup is complete, you may run the unit and integration tests. |
66 | 66 |
|
67 |
| -To have all the tests run successfully JDK 17 is required, since one of the tests builds the latest version of OpenSearch from source, and the OpenSearch project uses JDK 17 for this purpose. |
68 |
| -``` |
69 |
| -export JAVA_HOME=/path/to/JDK17 |
| 67 | +### Unit Tests |
70 | 68 |
|
71 | 69 | ```
|
| 70 | +make test |
72 | 71 |
|
73 |
| -Note that the `javadoc` executable should be available in the JDK installation. |
74 |
| - |
75 |
| -You could also use one of the following versions instead: 16, 15, 14, 13, 12, 11 or 8. Most of the complement of tests included will work with these. |
76 |
| - |
77 |
| -If you have multiple JDKs installed, export them in the following format `JAVA(jdk_version)_HOME`. Here is an example of how one would export JDK 8, 11, 15, 16: |
78 |
| -``` |
79 |
| -export JAVA8_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_231.jdk/Contents/Home/ |
80 |
| -export JAVA11_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.8.jdk/Contents/Home |
81 |
| -export JAVA15_HOME=/Library/Java/JavaVirtualMachines/amazon-corretto-15.jdk/Contents/Home/ |
82 |
| -export JAVA16_HOME=/Library/Java/JavaVirtualMachines/amazon-corretto-16.jdk/Contents/Home/ |
83 | 72 | ```
|
84 | 73 |
|
85 |
| -OpenSearch currently releases artifacts for the following operating systems: |
86 |
| -- Linux |
87 |
| -- Docker |
88 |
| -- FreeBSD |
| 74 | +### Integration Tests |
89 | 75 |
|
90 |
| -If the operating system is not listed above then the artifacts used will default to Linux. |
| 76 | +Integration tests can be run on the following operating systems: |
| 77 | + * RedHat |
| 78 | + * CentOS |
| 79 | + * Ubuntu |
| 80 | + * Amazon Linux 2 |
| 81 | + * MacOS |
91 | 82 |
|
92 |
| -For MacOS users running OpenSearch, please set JAVA_HOME to one of the local JDKs you exported as the JDK bundled with OpenSearch is not compatible with MacOS and prevent the metrics store from coming up correctly during integration tests. |
93 | 83 |
|
94 |
| -### Troubleshooting |
95 |
| -``` |
96 |
| -root WARNING Unable to get address info for address xxxxyyyy (AddressFamily.AF_INET, SocketKind.SOCK_DGRAM, 17, 0): <class 'socket.gaierror'> [Errno 8] nodename nor servname provided, or not known |
97 | 84 | ```
|
98 |
| -- VPN may be interfering. Try turning off the VPN. If you are connected to a VPN and face Docker-related issues when running the integration tests disconnecting from the VPN may fix this. |
| 85 | +make it |
99 | 86 |
|
100 | 87 | ```
|
101 |
| -Cannot download OpenSearch-1.0.1 |
102 |
| -``` |
103 |
| -- JAVA_HOME may not be correctly set. |
104 |
| - |
105 | 88 |
|
106 | 89 | ## Submitting your changes for a pull request
|
107 | 90 |
|
|
0 commit comments