From 5a48839448203d8032abca3ff5bfe6ec0fda88bc Mon Sep 17 00:00:00 2001 From: Ahson Khan Date: Tue, 23 Feb 2021 16:37:58 -0800 Subject: [PATCH] Update the root readme to include clear acquisition and installation details. (#1723) Things left to do (out-of-scope for this PR): - Add FAQ section for common errors and potential solutions when trying to build via vcpkg - Structure the doc with the following groups, if there is not a lot of overlap: - Windows - Visual Studio - VS Code - Command Line - Linux/Posix/Mac - VS Code - Command Line - Another dimension is `Vcpkg` vs `fetch content from GitHub` vs `build the SDK from source`. --- README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 125 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index bf181bfb0..14740a202 100644 --- a/README.md +++ b/README.md @@ -2,36 +2,144 @@ [![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/cpp/cpp%20-%20client%20-%20ci?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=1611&branchName=master) -This repository is for active development of the Azure SDK for C++. For consumers of the SDK we recommend visiting our [public developer docs](https://azure.github.io/azure-sdk-for-cpp) or our versioned [developer docs](https://azure.github.io/azure-sdk-for-cpp). +This repository is for active development of the Azure SDK for C++. For consumers of the SDK we recommend visiting our [developer docs](https://azure.github.io/azure-sdk-for-cpp). ## Getting started -To get started with a library, see the **README.md** file located in the library's project folder. You can find these library folders grouped by service in the `/sdk` directory. +For the best development experience, we recommend developers use [CMake projects in Visual Studio](https://docs.microsoft.com/cpp/build/cmake-projects-in-visual-studio?view=vs-2019) to view and build the source code together with its dependencies. You can also use any other text editor of your choice, such as [VS Code](https://code.visualstudio.com/), along with the command line for building your application with the SDK. -For tutorials, samples, quick starts, and other documentation, go to [Azure for C++ Developers](https://azure.github.io/azure-sdk-for-cpp). +You can find additional information for specific libraries by navigating to the appropriate folder in the `/sdk` directory. See the **README.md** file located in the library's project folder, for example, the [Azure Storage client library](https://github.com/Azure/azure-sdk-for-cpp/tree/master/sdk/storage#azure-storage-client-library-for-c). + +For API reference docs, tutorials, samples, quick starts, and other documentation, go to [Azure SDK for C++ Developer Docs](https://azure.github.io/azure-sdk-for-cpp). + +### Download & Install the SDK + +The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. You will need to install [Git](https://git-scm.com/downloads) before getting started. + +First clone and bootstrap vcpkg itself. You can install it anywhere on your machine, but **make note** of the directory where you clone the vcpkg repo. + +```cmd +> git clone https://github.com/microsoft/vcpkg +``` + +On Windows: + +```cmd +> .\vcpkg\bootstrap-vcpkg.bat +``` + +On Linux: + +```sh +> ./vcpkg/bootstrap-vcpkg.sh +``` + +To install the libraries for your project, run the following, optionally specifying the triplet. For example, the following will install packages for the `x64-windows` triplet. On Windows, not specifying a triplet will default to `x86-windows`: + +```cmd +> .\vcpkg\vcpkg install azure-storage-blobs-cpp:x64-windows +``` + +See the [list of packages](https://github.com/Azure/azure-sdk-for-cpp#vcpkg) available via vcpkg below. All Azure C++ SDK package names start with `azure-`. You can also search for the libraries you need with the `search` command. For example: + +```cmd +> .\vcpkg\vcpkg search azure- +``` + +Once the library is installed, follow the instructions from the console output to include the library in your `CMake` application. For example, to include `azure-storage-blobs-cpp`, add the following to your `CMakeLists.txt` file: + +```CMake +find_package(azure-storage-blobs-cpp CONFIG REQUIRED) +target_link_libraries(myProject PRIVATE Azure::azure-storage-blobs) +``` + +> NOTE: All the Azure client libraries take a dependency on `azure-core-cpp` which provides functionality commonly needed by all Azure clients. When you install any client library via vcpkg, it will bring in all the necessary dependencies as well. You don't need to install those individually to get started. + +You can reference this [vcpkg Quick Start](https://github.com/microsoft/vcpkg#quick-start-windows) for more details. + +### Building your Application + +In order to use the SDK installed via vcpkg with CMake, you can use the toolchain file from vcpkg: + +```cmd +> cmake -B [build directory] -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg repo]/scripts/buildsystems/vcpkg.cmake +> cmake --build [build directory] +``` + +The **entry point** for most scenarios when using the SDK will be a top-level client type corresponding to the Azure service you want to talk to. For example, sending requests to blob storage can be done via the `Azure::Storage::Blobs::BlobClient` API. + +All the Azure C++ SDK headers needed to be included are located within the `` folder, with sub-folders corresponding to each service. Similarly, all types and APIs can be found within the `Azure::` namespace. For example, to use functionality form `Azure::Core`, include the following header at the beginning of your application `#include `. + +Here's an example application to help you get started: + +```C++ +#include +#include +#include + +using namespace Azure::Storage::Blobs; + +// Get the required connection string/key from an environment variable or Azure KeyVault. +std::string GetConnectionString(); + +int main() +{ + std::string containerName = "testcontainer"; + std::string blobName = "sample-blob"; + + try + { + auto client = BlobClient::CreateFromConnectionString( + GetConnectionString(), containerName, blobName); + } + catch (const Azure::Core::RequestFailedException& e) + { + std::cout << e.what() << std::endl; + return 1; + } + return 0; +} +``` + +#### Visual Studio - CMakeSettings.json + +When building your application via Visual Studio, you can create and update a `CMakeSettings.json` file and include the following properties to let Visual Studio know where the packages are installed and which triplet needs to be used: + +```json +{ + "configurations": [ + { + "cmakeToolchain": "/vcpkg/scripts/buildsystems/vcpkg.cmake", + "variables": [ + { + "name": "VCPKG_TARGET_TRIPLET", + "value": "x64-windows", + "type": "STRING" + } + ] + } + ] +} +``` + +### Azure Requirements + +To call Azure services, you must first have an Azure subscription. Sign up for a [free trial](https://azure.microsoft.com/pricing/free-trial/) or use your [MSDN subscriber benefits](https://azure.microsoft.com/pricing/member-offers/msdn-benefits-details/). ## Packages available -Each service might have a number of libraries available from each of the following categories: -* [Client - New Releases](#client-new-releases) -* [Client - Previous Versions](#client-previous-versions) -### Client: New Releases +Each service might have a number of libraries available. These libraries follow the [Azure SDK Design Guidelines for C++](https://azure.github.io/azure-sdk/cpp_introduction.html) and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features at [Azure::Core](https://github.com/Azure/azure-sdk-for-cpp/blob/master/sdk/core/azure-core/README.md). -New wave of packages that we are announcing as **GA** and several that are currently releasing in **beta**. These libraries follow the [Azure SDK Design Guidelines for C++](https://azure.github.io/azure-sdk/cpp_introduction.html) and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features at [Azure::Core](https://github.com/Azure/azure-sdk-for-cpp/blob/master/sdk/core/azure-core/README.md). - -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`. +The 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/#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. -### Client: Previous Versions +### Vcpkg -Last stable versions of packages that are production-ready. These libraries provide similar functionalities to the beta packages, as they allow you to use and consume existing resources and interact with them, for example: upload a storage blob. They might not implement the [guidelines](https://azure.github.io/azure-sdk/cpp_introduction.html) or have the same feature set. They do however offer wider coverage of services. +The following SDK library releases are available on [vcpkg](https://github.com/microsoft/vcpkg): -### VcPkg - -Released SDK library versions are available on [VcPkg](https://github.com/microsoft/vcpkg): * `azure-core-cpp` * `azure-identity-cpp` * `azure-storage-blobs-cpp` @@ -39,8 +147,7 @@ Released SDK library versions are available on [VcPkg](https://github.com/micros * `azure-storage-files-datalake-cpp` * `azure-storage-files-shares-cpp` -> NOTE: In case of getting linker errors when consuming the SDK on Windows, make sure that [VcPkg trilet](https://vcpkg.readthedocs.io/en/latest/users/triplets/) being consumed matches the [CRT link flags](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library?view=msvc-160) being set for your app or library build. See also `MSVC_USE_STATIC_CRT` build flag. - +> NOTE: In case of getting linker errors when consuming the SDK on Windows, make sure that [vcpkg triplet](https://vcpkg.readthedocs.io/en/latest/users/triplets/) being consumed matches the [CRT link flags](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library?view=msvc-160) being set for your app or library build. See also `MSVC_USE_STATIC_CRT` build flag. ## Need help @@ -84,6 +191,7 @@ Many people all over the world have helped make this project better. You'll wan Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) . You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue). ### License + Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-cpp/blob/master/LICENSE.txt) license. ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-cpp%2FREADME.png)