Update Readme and Contribute to Oct07-2020 release instructions (#712)
* Update Readme and Contribute to Oct07-2020 release instructions
This commit is contained in:
Victor Vazquez
GitHub
parent
d4ff61919f
commit
f9e6acb358
@ -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)
|
||||
|
||||
|
||||
140
CONTRIBUTING.md
140
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 <vcpkg commit>
|
||||
|
||||
# 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.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>Option</td>
|
||||
<td>Description</td>
|
||||
<td>Default Value</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BUILD_TESTING</td>
|
||||
<td>Generates Unit Test for compilation. CMake will automatically download and build g-test.<br>After Compiling, use `ctest` to run Unit Test.</td>
|
||||
<td>OFF</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BUILD_STORAGE_SAMPLES</td>
|
||||
<td>Build Azure Storage clients sample application.</td>
|
||||
<td>OFF</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>RUN_LONG_UNIT_TESTS</td>
|
||||
<td>Enables 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.</td>
|
||||
<td>OFF</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WARNINGS_AS_ERRORS</td>
|
||||
<td>Warnings will make compiling fail</td>
|
||||
<td>ON</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BUILD_CURL_TRANSPORT</td>
|
||||
<td>Build the curl http transport adapter. When building on Posix systems, if no other transport adapter is built, this option will be automatically turned ON</td>
|
||||
<td>OFF</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>BUILD_DOCUMENTATION</td>
|
||||
<td>Build Doxygen documentation</td>
|
||||
<td>OFF</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
#### 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.
|
||||
|
||||
@ -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++]<!--https://azuresdkartifacts.blob.core.windows.net/azure-sdk-for-cpp/index.html-->.
|
||||
- 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.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user