Merge pull request #1012 from jordanw-bq/odbc-doc-updates

Update ODBC documentation

sql-odbc/docs/dev/BUILD_INSTRUCTIONS.md

@@ -2,85 +2,104 @@
 
 ## 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_<config><bitness>.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 `<odbc-root>\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_<config><bitness>.ps1` to build the driver from a Developer Powershell prompt.
+```
+.\build_win_<config><bitness>.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: `<odbc-root>\build\odbc\cmake\global_make_list.sln`.
 
-### Build Output
+### Output
 
 ```
 build
-└-- <Configuration><Bitness>
-  └-- odbc
-    └-- bin
-      └-- <Configuration>
-    └-- build
-    └-- lib
-  └-- aws-sdk
-    └-- build
-    └-- install
+└-- odbc
+  └-- bin
+    └-- <Configuration>
+  └-- cmake
+  └-- lib
+└-- aws-sdk
+  └-- build
+  └-- install
 ```
 
-* Driver DLL: `.\build\<Config><Bitness>\odbc\bin\<Config>\odfesqlodbc.dll`
-* Test binaries folder: `.\build\<Config><Bitness>\odbc\bin\<Config>`
+* Driver DLL: `.\build\odbc\bin\<Config>\odfesqlodbc.dll`
+* Test binaries folder: `.\build\odbc\bin\<Config>\`
 
 ### Packaging
 
-From a Developer Powershell, run:
+**Note:** If you make changes to the driver code or CMake project files, re-run the `build_windows_<config><bitness>.sh` script before running the following command.
+
 ```
-msbuild .\build\Release<Bitness>\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-<version>-Windows-<Bitness>-bit.msi` will be generated in the build directory.
+`Open Distro for Elasticsearch SQL ODBC Driver-<version>-Windows-<Bitness>-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_<config><bitness>.sh
+```
 
-`./build_mac_<config><bitness>.sh`
+### Output
 
-### Output Location on Mac
+```
+build
+└-- odbc
+  └-- bin
+  └-- lib
+└-- cmake-build64
+  └-- <build files>
+```
 
-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 .
+**Note:** If you make changes to the driver code or CMake project files, re-run the `build_mac_<config><bitness>.sh` script before running the following command.
+
+```
+cd cmake-build64/
+cpack .
+```
+
+`Open Distro for Elasticsearch SQL ODBC Driver-<version>-Darwin.pkg` will be generated in the build directory.
 
-Installer named as `Open Distro for Elasticsearch SQL ODBC Driver-<version>-Darwin.pkg` will be generated in the build directory.
+### Testing
+See [run_tests.md](./run_tests.md)
 
 ## General Build Info
 

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=<project-dir>/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/<test_name>**
 
-### 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 <rest-of-cmake-command>
 ```
 
 To get coverage for the driver library, you must use the `ccov-all` target, which runs all test suites and components with coverage.