azure-storage-cpplite/README.md

Azure Storage C++ Client Library (Lite)

About

The Azure Storage Client Library (Lite) for C++ allows you to build applications against Microsoft Azure Storage's blob service. This is a minimum dependency version that provide basic object storage. For an overview of Azure Storage, see Introduction to Microsoft Azure Storage. If you want to use other services of Azure Storage, or a more comprehensive functionality of Blob service, please see Azure Storage C++ Client Library.

Features

The full supported Azure Storage API can be found in the following list, please be aware that only part of the functionality of some APIs are supported:

• List Containers.
• Create Container.
• Get Container Properties.
• Delete Container.
• List Blobs.
• Put Blob.
• Get Blob.
• Get Blob Properties.
• Delete Blob.
• Copy Blob.
• Put Block.
• Put Block List.
• Get Block List.
• Put Page.
• Get Page Ranges.
• Append Block.

Installation

Supported Platforms

Please be aware that below platforms are tested and verified, but other platforms beyond this list can be working with some modification on the build steps resolving the dependencies. Feel free to test them out and contribute back.

• Ubuntu 16.04 x86_64.
• CentOS 6 x86_64.
• CentOS 7 x86_64.
• macOS Mojave version 10.14.6 x86_64.
• Windows 10 with Visual Studio 2017, x86 or x64.

Build this library on Linux or macOS

Project dependencies:

• GnuTLS (or OpenSSL v1.0.1)
• libcurl v7.35.0
• CMake v3.6
• GNU C++ or Apple clang with C++11 support
• libuuid 2.13.1

Clone the latest code from this repository:

git clone https://github.com/azure/azure-storage-cpplite.git

Install the dependencies, e.g. on Ubuntu:

apt install libssl-dev libcurl4-openssl-dev cmake g++ uuid-dev

Or, on CentOS:

yum install openssl-devel libcurl-devel cmake3 gcc-c++ libuuid-devel

Or, on macOS:

brew install openssl cmake

Please be aware that CentOS 6 comes with GCC version 4.4.7, which does not meet the requirement of this SDK. In order to use this SDK, devtoolset needs to be installed properly. Please be aware that on some Linux distributions, pkg-config is not properly installed that would result in CMake not behaving as expected. Installing pkg-config or updating it will eliminate the potential issue. The tested version of pkg-config is 0.27.1.

Build and install azure-storage-cpplite:

cd azure-storage-cpplite
mkdir build.release
cd build.release
cmake .. -DCMAKE_BUILD_TYPE=Release
# Just build
cmake --build .
# Or build and install
cmake --build . --target install

Use GnuTLS instead of OpenSSL:

Alternatively, you can use GnuTLS instead of OpenSSL. Simply install GnuTLS and add the argument -DUSE_OPENSSL=OFF during CMake configure.

Build this library on Windows

Project dependencies:

• OpenSSL v1.0.2
• libcurl v7.60.0
• CMake v3.6
• Visual Studio 2017

Clone the latest code from this repository:

git clone https://github.com/azure/azure-storage-cpplite.git

Prepare and install the dependencies.

There are two major dependencies on Windows: libcurl and OpenSSL. For the best development experience, we recommend that developers use vcpkg to install dependencies. You can also install your own choice of pre-built binaries.

vcpkg install curl openssl

Build azure-storage-cpplite using CMake in command line

cd azure-storage-cpplite
mkdir build.release
cd build.release
cmake .. -DCMAKE_TOOLCHAIN_FILE=<vcpkg path>/scripts/buildsystems/vcpkg.cmake
cmake --build . --config Release

Specifying customized OpenSSL or libcurl root folder

Default OpenSSL or libcurl root directory may not be applicable for all users. In that case, following parameters can be used to specify the preferred path: -DCURL_INCLUDE_DIR=<libcurl's include directory>, -DCURL_LIBRARY=<libcurl's library path>, -DOPENSSL_ROOT_DIR=<OpenSSL's root directory>.

This applies to both Windows and Unix.

Other build options

There are some advanced options to config the build when using CMake commands:

• -DBUILD_SHARED_LIBS= : specify ON or OFF to control if shared library or static library should be built.
• -DBUILD_TESTS= : specify ON or OFF to control if tests should be built.
• -DBUILD_SAMPLES= : specify ON or OFF to control if samples should be built.
• -A : specify Win32 or x64 to config the generator platform type on Windows.
• -DCMAKE_BUILD_TYPE= : specify Debug or Release to config the build type on Linux or macOS.
• --config : specify Debug or Release to config the build type on Windows.

Usage

Simply include the header files after installing the library, everything is good to go. For a more comprehensive sample, please see sample. To build the sample, add -DBUILD_SAMPLES=ON when building the repository.

#include "storage_credential.h"
#include "storage_account.h"
#include "blob/blob_client.h"

// Your settings
std::string account_name = "YOUR_ACCOUNT_NAME";
std::string account_key = "YOUR_ACCOUNT_KEY";
bool use_https = true;
std::string blob_endpoint = "CUSTOMIZED_BLOB_ENDPOINT";
int connection_count = 2;

// Setup the client
azure::storage_lite::shared_key_credential credential(account_name, account_key);
azure::storage_lite::storage_account(account_name, credential, use_https, blob_endpoint);
azure::storage_lite::blob_client client(storage_account, connection_count);

// Start using
auto outcome = client.create_container("YOUR_CONTAINER_NAME").get();

License

This project is licensed under MIT.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

When contributing to this client library, there are following ground rules:

1. All source code change should be clearly addressing issues or adding new features, and should be covered with test.
2. Coding style should match with the existing code.
3. Any contribution should not degrade performance or complex functionality.
4. Introducing new dependency should be done with much great caution. Any new dependency should introduce significant performance improvement or unblock critical user scenario.

Build Test

Install Catch2 via package manager, or download Catch2 single header version and specify the location with -DCATCH2_INCLUDE_DIR=<catch2 path> when build.

Add -DBUILD_TESTS=ON when building the repository.

Please modify the connection string here to successfully run the tests. All the tests use standard Azure Storage account.

Please note that in order to run test, a minimum version of g++ 5.1 is required on Linux, and Visual Studio 2017 is required on Windows.