From dc801de7d0729b7b87bd60b37c245e22a4b3cb8b Mon Sep 17 00:00:00 2001 From: Jordan Wilson Date: Tue, 26 Jan 2021 12:40:55 -0800 Subject: [PATCH 1/2] fix out-of-date/unclear ODBC documentation --- sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md | 103 ++++++++++++++---------- sql-odbc/docs/dev/run_tests.md | 43 +++++----- 2 files changed, 83 insertions(+), 63 deletions(-) diff --git a/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md b/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md index f7d60cc949..2f6fa83530 100644 --- a/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md +++ b/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md @@ -2,85 +2,100 @@ ## Windows -### Dependencies +### Requirements -* [cmake](https://cmake.org/install/) -* [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) (Other versions may work, but only 2019 has been tested) -* [ODBC Driver source code](https://github.com/opendistro-for-elasticsearch/sql/tree/master/sql-odbc) +* Install [cmake](https://cmake.org/install/) +* Install [Visual Studio 2019](https://visualstudio.microsoft.com/vs/) + * Other versions may work, but only 2019 has been tested -### Build +**NOTE:** All Windows/`.ps1` scripts must be run from a [Developer Powershell](https://devblogs.microsoft.com/visualstudio/the-powershell-you-know-and-love-now-with-a-side-of-visual-studio/). -#### with Visual Studio +> A shortcut is installed on your system with Visual Studio (**"Developer Powershell for VS 2019"**) -Run `./build_win_.ps1` to generate a VS2019 project for building/testing the driver. (the build may fail, but should still generate a `.sln` file) +> Programs launched with this prompt (ex: VS Code) also have access to the Developer shell. -The solution can be found at `\build\odbc\build\global_make_list.sln`. +> For more information regarding the Developer Powershell: https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160 -#### with Developer Powershell +### Build -Use `./build_win_.ps1` to build the driver from a Developer Powershell prompt. +``` +.\build_win_.ps1 +``` -> A shortcut is installed on your system with Visual Studio (search for **"Developer Powershell for VS 2019"**) +A Visual Studio 2019 solution will also be generated for building/testing the driver with Visual Studio. (Note: if the build fails, the solution will still be generated.) -> Programs launched with this prompt (ex: VS Code) also have access to the Developer shell. +Solution file: `\build\odbc\cmake\global_make_list.sln`. -### Build Output +### Output ``` build -└-- - └-- odbc - └-- bin - └-- - └-- build - └-- lib - └-- aws-sdk - └-- build - └-- install +└-- odbc + └-- bin + └-- + └-- cmake + └-- lib +└-- aws-sdk + └-- build + └-- install ``` -* Driver DLL: `.\build\\odbc\bin\\odfesqlodbc.dll` -* Test binaries folder: `.\build\\odbc\bin\` +* Driver DLL: `.\build\odbc\bin\\odfesqlodbc.dll` +* Test binaries folder: `.\build\odbc\bin\\` ### Packaging -From a Developer Powershell, run: ``` -msbuild .\build\Release\odbc\PACKAGE.vcxproj -p:Configuration=Release +msbuild .\build\odbc\PACKAGE.vcxproj -p:Configuration=Release ``` -An installer named as `Open Distro for Elasticsearch SQL ODBC Driver--Windows--bit.msi` will be generated in the build directory. +`Open Distro for Elasticsearch SQL ODBC Driver--Windows--bit.msi` will be generated in the build directory. +### Testing +See [run_tests.md](./run_tests.md) ## Mac -(TODO: upgrade build scripts & documentation for Mac) -### Dependencies +### Requirements -Homebrew must be installed to manage packages, to install homebrew see the [homebrew homepage](https://brew.sh/). -Using homebrew, install the following packages using the command provided: ->brew install [package] -> ->* curl ->* cmake ->* libiodbc +[Homebrew](https://brew.sh/) is required for installing the following necessary packages. +``` +brew install curl +brew install cmake +brew install libiodbc +``` -### Building the Driver +### Build -From a Bash shell: +``` +./build_mac_.sh +``` -`./build_mac_.sh` +### Output -### Output Location on Mac +``` +build +└-- odbc + └-- bin + └-- lib +└-- cmake-build64 + └-- +``` -Compiling on Mac will output the tests to **bin64** and the driver to **lib64**. There are also some additional test infrastructure files which output to the **lib64** directory. +* Driver library: `./build/odbc/lib/libodfesqlodbc.dylib` +* Test binaries folder: `./build/odbc/bin/` ### Packaging -Run below command from the project's build directory. ->cpack . +``` +cd cmake-build64/ +cpack . +``` + +`Open Distro for Elasticsearch SQL ODBC Driver--Darwin.pkg` will be generated in the build directory. -Installer named as `Open Distro for Elasticsearch SQL ODBC Driver--Darwin.pkg` will be generated in the build directory. +### Testing +See [run_tests.md](./run_tests.md) ## General Build Info diff --git a/sql-odbc/docs/dev/run_tests.md b/sql-odbc/docs/dev/run_tests.md index 903e5f8f0a..8f7fb1b87a 100644 --- a/sql-odbc/docs/dev/run_tests.md +++ b/sql-odbc/docs/dev/run_tests.md @@ -1,14 +1,16 @@ # ODFE SQL ODBC Driver Testing -## Preparation +## Requirements * Latest version of [Open Distro for Elasticsearch](https://opendistro.github.io/for-elasticsearch-docs/docs/install/) +* [Required datasets loaded](#set-up-test-datasets) +* [DSN configured](#set-up-dsn) -### Loading Test Datasets +### Set up test datasets -Loading a dataset requires an [elasticsearch](https://opendistro.github.io/for-elasticsearch-docs/docs/install/) service running with [kibana](https://opendistro.github.io/for-elasticsearch-docs/docs/kibana/). If either of these are missing, please refer to the documentation on how to set them up. +Loading a dataset requires an [OpenDistro for Elasticsearch](https://opendistro.github.io/for-elasticsearch-docs/docs/install/) service running with [Kibana](https://opendistro.github.io/for-elasticsearch-docs/docs/kibana/). If either of these are missing, please refer to the documentation on how to set them up. -Note, if you wish to work with SSL/TLS, you need to configure Elasticsearch and Kibana to support it. See Working With SSL/TLS below. +Note, if you wish to work with SSL/TLS, you need to configure ODFE and Kibana to support it. See the [build instructions](./BUILD_INSTRUCTIONS.md) for more info. First load the sample datasets provided by kibana. @@ -23,14 +25,9 @@ Select the wrench on the left control panel. Enter the following commands into t * [kibana_sample_data_types](./datasets/kibana_sample_data_types.md) -## Running Tests - -Tests can be **executed directly**, or by using the **Test Runner**. - -**NOTES:** +### Set up DSN -* A test DSN named `test_dsn` must be set up in order for certain tests in ITODBCConnection to pass. To configure the DSN, see the instructions, below. -* Datasets must be loaded into Elasticsearch using [kibana](https://www.elastic.co/guide/en/kibana/current/connect-to-elasticsearch.html). See the section on loading datasets below. +A test DSN named `test_dsn` must be set up in order for certain tests in ITODBCConnection to pass. To configure the DSN, see the instructions below. ### Windows Test DSN Setup @@ -50,7 +47,12 @@ Tests can be **executed directly**, or by using the **Test Runner**. * `export ODBCINSTINI=/src/IntegrationTests/ITODBCConnection/test_odbcinst.ini` * Manually add the entries to your existing `odbc.ini` and `odbcinst.ini` entries. (normally found at `~/.odbc.ini` and `~/.odbcinst.ini`) -### Running Tests directly on Windows +## Running Tests +Tests can be executed directly, or by using the **Test Runner**. + +### Direct + +#### Windows Tests can be executed directly using **Visual Studio** by setting the desired test as a **Start up Project** @@ -60,23 +62,23 @@ Tests can be executed directly using **Visual Studio** by setting the desired te For more information, see the [Visual Studio Console Application documentation](https://docs.microsoft.com/en-us/cpp/build/vscpp-step-2-build?view=vs-2019). -### Running Tests directly on Mac +#### Mac Tests can be executed using a command line interface. From the project root directory, enter: > **bin64/** -### Running Tests using the Test Runner +### Test Runner The **Test Runner** requires [python](https://wiki.python.org/moin/BeginnersGuide/Download) to be installed on the system. Running the **Test Runner** will execute all the tests and compile a report with the results. The report indicates the execution status of all tests along with the execution time. To find error details of any failed test, hover over the test. -#### Running Tests using the Test Runner on Windows +#### Windows Open the project's root directory in a command line interface of your choice. Execute >**.\run_test_runner.bat** The **Test Runner** has been tried and tested with [Python3.8](https://www.python.org/downloads/release/python-380/) on **Windows systems**. Other versions of Python may work, but are untested. -#### Running Tests using the Test Runner on Mac +#### Mac Open the project's root directory in a command line interface of your choice. Execute >**./run_test_runner.sh** @@ -87,12 +89,15 @@ The **Test Runner** has been tried and tested with [Python3.7.6](https://www.pyt (using a CMake script provided by George Cave (StableCoder) under the Apache 2.0 license, found [here](https://github.com/StableCoder/cmake-scripts/blob/master/code-coverage.cmake)) -> **NOTE**: Before building with coverage, make sure the following directory is in your PATH environment variable: -> `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin` +#### Requirements +* `llvm-cov` in your PATH environment variable + * Possible locations for this binary: + * `/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin` + * `/Library/Developer/CommandLineTools/usr/bin` To build the tests with code coverage enabled, set the `CODE_COVERAGE` variable to `ON` when preparing your CMake build. ```bash -cmake ... -DBUILD_WITH_TESTS=ON -DCODE_COVERAGE=ON +cmake -DBUILD_WITH_TESTS=ON -DCODE_COVERAGE=ON ``` To get coverage for the driver library, you must use the `ccov-all` target, which runs all test suites and components with coverage. From bc119b12dd9f2ab1a01706f95a63f4ddd4e11d37 Mon Sep 17 00:00:00 2001 From: Jordan Wilson Date: Tue, 26 Jan 2021 13:57:10 -0800 Subject: [PATCH 2/2] clarify that re-build might be required for packaging steps --- sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md b/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md index 2f6fa83530..41dbf888ba 100644 --- a/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md +++ b/sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md @@ -45,6 +45,8 @@ build ### Packaging +**Note:** If you make changes to the driver code or CMake project files, re-run the `build_windows_.sh` script before running the following command. + ``` msbuild .\build\odbc\PACKAGE.vcxproj -p:Configuration=Release ``` @@ -87,6 +89,8 @@ build ### Packaging +**Note:** If you make changes to the driver code or CMake project files, re-run the `build_mac_.sh` script before running the following command. + ``` cd cmake-build64/ cpack .