README.md

﷽

Residue C++ Client

Official C++ client library with feature-rich API to interact with residue seamlessly. It uses Easylogging++ to interact and take input from the user. Easylogging++ is highly efficient, well-tested library.

Getting Started

This library is based on single source file. It automatically includes <residue/easylogging++.h> header and expect it to be available on developer's system. Please refer to documentation page to check the API.

Please refer to samples directory to get started

Download Binary

You can download binary from releases page for your platform. They are standalone libraries with dependency on libz that usually comes with operating system distribution.

• Download binaries archive for your platform
• Download headers archive
• Unzip binary archives and copy them to /usr/local/lib/
• Unzip header archives and copy them to /usr/local/include/residue/

For ease, we have setup install.sh that you can use to install it locall

sh -c "$(curl -fsSL https://raw.githubusercontent.com/abumq/residue-cpp/master/install.sh)"

You should be ready to link your application against libresidue, both statically and dynamically.

If you use cmake, you may also be interested in Residue CMake module

Undefined Reference

You may need to define -D_GLIBCXX_USE_CXX11_ABI=0 if you're using using gcc 5.1+ with pre-compiled binary. If you don't do it, you will get undefined references e.g,

/tmp/ccIYrKup.o: In function `Residue::connect(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, int)':
main.cc:(.text._ZN7Residue7connectERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEEi[_ZN7Residue7connectERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEEi]+0x27): undefined reference to `Residue::connect_(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, int, bool)'

Learn more

Build From Source

If you do not wish to download binaries, you can build your own library using following steps.

Dependencies

• C++11 compiler (or higher)
• Crypto++ v5.6.5+ with Pem Pack
• zlib-devel

Get The Code

You can either download code from master branch or clone it using git:

git clone git@github.com:abumq/residue-cpp.git

Build

Residue C++ library uses the CMake toolchains to create makefiles.

In a nutshell, you will do:

mkdir build
cd build
cmake -Dtest=ON ..
make

CMake Options

You can change following options in CMake (using -D<option>=ON)

Option	Description
test	Compile unit tests
build_sample_app	Builds detailed-cmake sample
special_edition	Build special edition

Run Tests

Please consider running unit test before you move on

make test

Install

The compilation process creates libresidue (static and shared) in build directory. Please see Static Library section below before installing. You can install it in system-wide directory using:

make install # Please read Static Library section below

If the default path (/usr/local/lib) is not where you want things installed, then set the CMAKE_INSTALL_PREFIX option when running cmake. e.g,

cmake .. -DCMAKE_INSTALL_PREFIX=/usr/lib

Setup

Make sure you have all the dependencies installed. You can use following script to install them and then go back to the Build section (tested on Ubuntu 14.04 (Trusty) 64-bit)

### Essentials
## Essentials
sudo apt-get install -y cmake build-essential libcurl-dev libz-dev
    # sudo yum install -y cmake curl-devel zlib-devel # for rpm
    # sudo yum groupinstall -y 'Development Tools'

## Google Testing Library
wget -O gtest.tar.gz https://github.com/google/googletest/archive/release-1.7.0.tar.gz
tar xf gtest.tar.gz
cd googletest-release-1.7.0
cmake -DBUILD_SHARED_LIBS=ON .
make
cp -a include/gtest /usr/local/include
cp -a libgtest_main.* libgtest.* /usr/local/lib/
cd ..

## Crypto++
wget https://raw.githubusercontent.com/abumq/abumq.github.io/master/downloads/cryptocpp.tar.gz
tar xf cryptocpp.tar.gz
cd cryptopp-CRYPTOPP_5_6_5
wget https://raw.githubusercontent.com/abumq/abumq.github.io/master/downloads/pem_pack.zip
unzip pem_pack.zip
### IF ON MACOS ALSO DO
### export CC=`which clang`
### export CXX=`which clang++`
cmake .
make
sudo make install

Static Library

By default, residue builds shared and static libraries. But static library only contains residue specific objects.

You can use following command to produce correct static library that is independent of any other library.

mkdir build
cd build
sh ../tools/package.sh linux 1.1.0 # specify version carefully to match with what's in CMakeLists.txt

This will create:

• libresidue-1.1.0-x86_64-linux.tar.gz
• libresidue-1.1.0-static-x86_64-linux.tar.gz

Second one (libresidue-1.1.0-static-x86_64-linux.tar.gz) contains static library that is fully independent.

Strip

You can take advantage strip if you wish to link your application statically. This will reduce binary size significantly.

Build Matrix

Branch	Platform	Build Status
develop	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / clang++
develop	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-4.9
develop	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-5
develop	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-6
develop	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-7
master	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / clang++
master	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-4.9
master	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-5
master	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-6
master	GNU/Linux 4.4 / Ubuntu 4.8.4 64-bit / g++-7

License

Copyright 2017-present @abumq (Majid Q.)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.