From f9e6acb3588e400abb4be993fd61e1bc5d62c94a Mon Sep 17 00:00:00 2001 From: Victor Vazquez Date: Wed, 14 Oct 2020 22:00:34 -0700 Subject: [PATCH] Update Readme and Contribute to Oct07-2020 release instructions (#712) * Update Readme and Contribute to Oct07-2020 release instructions --- CMakeLists.txt | 1 + CONTRIBUTING.md | 140 +++++++++++++++++++++++------------------- README.md | 4 +- sdk/storage/README.md | 2 +- 4 files changed, 79 insertions(+), 68 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index a0ff4187a..d761950bf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,6 +11,7 @@ option(BUILD_TRANSPORT_WINHTTP "Build an HTTP transport implementation with WIN option(BUILD_TESTING "Build test cases" OFF) option(BUILD_DOCUMENTATION "Create HTML based API documentation (requires Doxygen)" OFF) option(RUN_LONG_UNIT_TESTS "Tests that takes more than 5 minutes to complete. No effect if BUILD_TESTING is OFF" OFF) +option(BUILD_STORAGE_SAMPLES "Build sample application for Azure Storage clients" OFF) include(DefineTransportAdapter) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 175dcfce3..891fbe3e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,97 +50,109 @@ Merging Pull Requests (for project contributors with write access) ### Pre-requisites -This project contains Git submodules which are required to build. After cloning this repo, run `git submodule update ---init --recursive`. - -### CMake -CMake version 3.12 or higher is required to build these libraries. Download and install CMake from the project's +#### CMake +CMake version 3.13 or higher is required to build these libraries. Download and install CMake from the project's [website](https://cmake.org/download/). -### Vcpkg -Vcpkg is required to download project dependencies. To get started, first clone vcpkg to a location on your system and -run the bootstrapping script. +#### Third Party Dependencies +- curl +- libxml2 + +Vcpkg can be used to install the Azure SDK for CPP dependencies into a specific folder on the system instead of globally installing them. +Follow [vcpkg install guide](https://github.com/microsoft/vcpkg#getting-started) to get vcpkg and install the following dependencies: ```sh -git clone https://github.com/Microsoft/vcpkg.git -cd vcpkg # Keep note of the location of this directory for the next step -Windows> .\bootstrap-vcpkg.bat -Linux/macOS:~/$ ./bootstrap-vcpkg.sh +./vcpkg install curl libxml2 ``` -On macOS, this command may fail if your version of the C++ toolchain is not new enough to support vcpkg. To resolve -this, vcpkg recommends to install `gcc@6` from Homebrew (`brew install gcc@6`), then re-run the bootstrapping script. +When using vcpkg, make sure to set the `VCPKG_ROOT` environment variable to the vcpkg Git repository folder before using `CMake`. -Next, define the `VCPKG_ROOT` environment variable and add the `vcpkg` command to your path. You will probably want to -persist these changes, so it's recommended to add/edit them via the Windows "System Properties" control panel, or via -your `.profile` file on Linux/macOS. +The Azure SDK for C++ uses [this vcpkg release version](https://github.com/Azure/azure-sdk-for-cpp/blob/master/eng/vcpkg-commit.txt) for continuos integration (CI) building and testing. Make sure to checkout this version when following the next steps for building and running the Azure SDK for C++. Using a newer vcpkg version might still work, however, if it is tested. -> **Windows** -> ```bat -> set VCPKG_ROOT=C:\path\to\vcpkg -> set PATH=%PATH%;%VCPKG_ROOT% -> ``` -> -> **Linux/macOS** -> ```sh -> export VCPKG_ROOT=/path/to/vcpkg -> export PATH=$PATH:$VCPKG_ROOT -> ``` +```sh +# Checking out vcpkg release version before installing dependencies -Finally, install the project dependencies with vcpkg. - -> **Windows** -> ```bat -> set VCPKG_DEFAULT_TRIPLET=x64-windows-static -> vcpkg install curl[winssl] -> ``` -> -> **Linux/macOS** -> ```sh -> vcpkg install curl[ssl] -> ``` - -### Development headers (Linux/macOS) -On Linux/macOS the development headers for OpenSSL 1.1 must be installed to a location where CMake can find them. -For Ubuntu 18.04 and up, you can install them directly from the main Ubuntu repository with `apt-get`. For macOS, you -can install them with Homebrew. - -> **Linux (Ubuntu 18.04 and up)** -> ```sh -> sudo apt-get install libssl-dev -> ``` -> -> **macOS** -> ```sh -> brew install openssl@1.1 -> ``` +git clone https://github.com/Microsoft/vcpkg.git +cd vcpkg +# Checkout the vcpkg commit from the vcpkg-commit.txt file (link above) +git checkout +# build vcpkg (showing linux command, see vcpkg getting started for windows) +./bootstrap-vcpkg.sh +./vcpkg install curl libxml2 +``` + ### Building and Testing #### Building the project -First, ensure that the `VCPKG_ROOT` and `VCPKG_DEFAULT_TRIPLET` environment variables are set, as described [above](#vcpkg). This need to be defined -any time you want to build. Then generate the build files and build as you would any standard CMake project. From the +First, ensure that the `VCPKG_ROOT` environment variable is set, as described [above](#vcpkg). This needs to be defined +any time you want to build using vcpkg. Then generate the build files and build as you would with any standard CMake project. From the repo root, run: ```sh mkdir build cd build -cmake -Duse_default_uuid=ON .. +cmake .. cmake --build . ``` + +#### CMake build options +The following CMake options are available for adding/removing project features. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescriptionDefault Value
BUILD_TESTINGGenerates Unit Test for compilation. CMake will automatically download and build g-test.
After Compiling, use `ctest` to run Unit Test.		OFF
BUILD_STORAGE_SAMPLESBuild Azure Storage clients sample application.OFF
RUN_LONG_UNIT_TESTSEnables the special unit tests which takes more than 3 minutes to run. THis tests are for some specific features like the connection pool for curl transport adapter.OFF
WARNINGS_AS_ERRORSWarnings will make compiling failON
BUILD_CURL_TRANSPORTBuild the curl http transport adapter. When building on Posix systems, if no other transport adapter is built, this option will be automatically turned ONOFF
BUILD_DOCUMENTATIONBuild Doxygen documentationOFF
+ +#### Testing the project If you want to run tests also, generate build files using below command and then build. ```sh cmake -DBUILD_TESTING=ON .. cmake --build . ``` -#### Testing the project -Tests are executed via the `ctest` command included with CMake. From the repo root, run: +Tests are executed via the `ctest` command included with CMake. From the build directory, run: ```sh -cd build -ctest -C Debug +# use -V for verbose +ctest -V +# Use -N to list test that are part of test set +ctest -N +# Use -R to use a regular exp for what to run +ctest -R Http # runs only Http tests ``` ### Visual Studio 2019 -You can also build the project by simply opening the desired project directory in Visual Studio. Everything should be -preconfigured to build and run tests. +You can also build the project by simply opening the repo directory in Visual Studio. Visual Studio will detect the `CMake` file and will configure itself to generate, build and run tests. diff --git a/README.md b/README.md index 24ddffd76..a2d488e3a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ New wave of packages that we are announcing as **GA** and several that are curre These new client libraries can be identified by the naming used for their folder, package, and namespace. Each will start with `azure`, followed by the service category, and then the name of the service. For example `azure-storage-blobs`. -For a complete list of available packages, please see the [latest available packages](https://azure.github.io/azure-sdk/releases/latest/) page. +For a complete list of available packages, please see the [latest available packages](https://azure.github.io/azure-sdk/releases/latest/#c) page. > NOTE: If you need to ensure your code is ready for production we strongly recommend using one of the stable, non-beta libraries. @@ -33,7 +33,6 @@ Last stable versions of packages that are production-ready. These libraries prov - For reference documentation visit the [Azure SDK for C++ documentation](https://azure.github.io/azure-sdk-for-cpp). - For tutorials, samples, quick starts and other documentation, visit [Azure for C++ Developers](https://docs.microsoft.com/azure/). -- For build reports on code quality, test coverage, etc, visit [Azure SDK for C++]. - File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-cpp/issues/new/choose). ## Navigating the repository @@ -76,4 +75,3 @@ Security issues and bugs should be reported privately, via email, to the Microso Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-cpp/blob/master/LICENSE) license. ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-cpp%2FREADME.png) - diff --git a/sdk/storage/README.md b/sdk/storage/README.md index 01f6663f5..ffc992c92 100644 --- a/sdk/storage/README.md +++ b/sdk/storage/README.md @@ -54,7 +54,7 @@ vcpkg.exe install libxml2:x64-windows curl:x64-windows You can use the package manager on different Unix platforms to install the dependencies. The dependencies to be installed are: - - CMake 3.15.0 or higher. + - CMake 3.13.0 or higher. - libxml2. - OpenSSL. - libcurl.