Elastos Carrier Native SDK

Travis CI	GitHub CI	Circle	AppVeyor

Introduction

Elastos Carrier is a decentralized and encrypted peer-to-peer (P2P) communication framework that routes network traffic between virtual machines and Decentralized Applications (DApps).

The authentication process of peer nodes utilizes the Elastos Decentralized ID (DID) sidechain. （TODO）

Table of Contents

• Elastos Carrier Native SDK
  • Introduction
  • Table of Contents
  • Usage
  • Build on Ubuntu / Debian / Linux Host
    • 1. Brief introduction
    • 2. Install Pre-Requirements
    • 3. Build to run on host (Ubuntu / Debian / Linux)
    • 4. Run Elashell or Elatests
    • 5. Cross-compilation for Android Platform
    • 6. Cross-compilation for Raspberry Pi
  • Build on Raspberry Pi
    • 1. Brief introduction
    • 2. Install Pre-Requirements
    • 3. Build to run on host
    • 4. Run Elashell or Elatests
  • Build on MacOS Host
    • 1. Brief introduction
    • 2. Install Pre-Requirements
    • 3. Build to run on host
    • 4. Run Elashell or Elatests
    • 5. Cross-compilation for Android Platform
    • 6. Cross-compilation for iOS Platform
  • Build on Windows Host
    • 1. Brief introduction
    • 2. Set up Environment
    • 3. Build to run on host
    • 4. Run Elashell or Elatests
  • Build API Documentation
    • Build on Ubuntu / Debian / Linux Host
      • 1. Install Pre-Requirements
      • 2. Build
      • 3. View
  • Contribution
  • Acknowledgments
  • License

Usage

CMake is used to build, test and package the Elastos Carrier project in an operating system as well as compiler-independent manner.

Certain knowledge of CMake is required.

At the time of this writing, The compilation of sources works on macOS, Linux (Ubuntu, Debian etc.) and Windows, and provides the option to cross-compile for target systems of iOS, Android and RaspberryPi.

Build on Ubuntu / Debian / Linux Host

1. Brief introduction

On Ubuntu / Debian / Linux, besides the compilation for the host itself, cross-compilation is possible for the following targets:

• Android with architectures of armv7a, arm64 and simulators of x86/x86_64 are supported.
• RaspberryPi with architecture armv7l only.

2. Install Pre-Requirements

To generate Makefiles by using configure or cmake and manage dependencies of the Carrier project, certain packages must be installed on the host before compilation.

Run the following commands to install the prerequisite utilities:

sudo apt-get update
sudo apt-get install -f build-essential autoconf automake autopoint libtool flex bison libncurses5-dev cmake

Download this repository using Git:

git clone https://github.com/elastos/Elastos.NET.Carrier.Native.SDK

3. Build to run on host (Ubuntu / Debian / Linux)

To compile the project from source code for the target to run on Ubuntu / Debian / Linux, carry out the following steps:

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir linux
cd linux

Generate the Makefile in the current directory:

Note: Please see custom options below.

cmake ../..

---

Optional (Generate the Makefile): To be able to build a distribution with a specific build type Debug/Release, as well as with customized install location of distributions, run the following commands:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=YOUR-INSTALL-PATH ../..

---

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program:

Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

4. Run Elashell or Elatests

Elashell is a fully functional, lightweight shell program that processes commands and returns the output to the terminal. Through Elashell, users may connect to other carrier nodes and exchange messages.

Elatests is also a shell program, but with predefined commands, therefore no user interaction is necessary. The output for every command is displayed in the terminal for a simple evaluation of test results.

To run elashell or elatests, first extract the distribution package created previously and enter the extracted folder. Then, change directory to the 'bin' folder.

cd YOUR-DISTRIBUTION-PACKAGE-PATH/bin

Run Elashell:

./elashell

Available commands in the shell can be listed by using the command help. Specific command usage descriptions can be displayed by using help [Command] where [Command] must be replaced with the specific command name. For the entire command list please see the COMMANDS.md file.

Or run Elatests:

./elatests

5. Cross-compilation for Android Platform

With CMake, Elastos Carrier can be cross-compiled to run on Android as a target platform, while compilation is carried out on Ubuntu / Debian / Linux host.

Prerequisite: Android NDK 'android-ndk-r16b' or higher must be downloaded onto the Linux based host. Android NDKs (such as 'Linux 64-bit (x86)') can be downloaded from Android developer web site . Please make sure to extract the downloaded NDK.

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir android
cd android

To generate the required Makefile in the current directory, please make sure to first replace 'YOUR-TARGET-ARCHITECTURE' and 'YOUR-ANDROID-NDK-HOME' with the correct option and path.

-DANDROID_ABI accepts the following target architecture options:

• armeabi-v7a
• arm64-v8a
• x86
• x86_64

Replace 'YOUR-ANDROID-NDK-HOME' with the path to the extracted NDK folder.

Run the command with the correct options described above:

cmake -DANDROID_ABI=YOUR-TARGET-ARCHITECTURE -DANDROID_NDK_HOME=YOUR-ANDROID-NDK-HOME -DCMAKE_TOOLCHAIN_FILE=../../cmake/AndroidToolchain.cmake ../..

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program: Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

6. Cross-compilation for Raspberry Pi

With CMake, Elastos Carrier can be cross-compiled to run on Raspberry Pi (Raspbian OS) as a target platform, while compilation is carried out on Ubuntu / Debian / Linux host.

Prerequisite: The Raspberry Pi Toolchain must be downloaded onto the host Linux based host.

git clone https://github.com/raspberrypi/tools

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir rpi
cd rpi

To generate the required Makefile in the current directory, please make sure to first replace 'YOUR-RASPBERRYPI-TOOLCHAIN-HOME' with the correct path to the previously downloaded Raspberry Pi Toolchain folder.

Run the command with the correct option described above:

cmake -DRPI_TOOLCHAIN_HOME=YOUR-RASPBERRYPI-TOOLCHAIN-HOME -DCMAKE_TOOLCHAIN_FILE=../../cmake/RPiToolchain.cmake ../..

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program:

Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

Build on Raspberry Pi

1. Brief introduction

With CMake, Elastos Carrier can be cross-compiled to run only on Raspberry Pi as target platform, while compilation is carried out on a Raspberry Pi host.

2. Install Pre-Requirements

To generate Makefiles by using configure or cmake and manage dependencies of the Carrier project, certain packages must be installed on the host before compilation.

Run the following commands to install the prerequisite utilities:

sudo apt-get update
sudo apt-get install -f build-essential autoconf automake autopoint libtool flex bison libncurses5-dev cmake

Download this repository using Git:

git clone https://github.com/elastos/Elastos.NET.Carrier.Native.SDK

3. Build to run on host

To compile the project from source code for the target to run on Raspberry Pi, carry out the following steps:

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir pi
cd pi

Generate the Makefile in the current directory:

Note: Please see custom options below.

cmake -DBUILD_ON_RPI=ON ../..

---

Optional (Generate the Makefile): To be able to build a distribution with a specific build type Debug/Release, as well as with customized install location of distributions, run the following commands:

cmake -DBUILD_ON_RPI=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=YOUR-INSTALL-PATH ../..

---

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

4. Run Elashell or Elatests

Elashell is a fully functional, lightweight shell program that processes commands and returns the output to the terminal. Through Elashell, users may connect to other carrier nodes and exchange messages.

Elatests is also a shell program, but with predefined commands, therefore no user interaction is necessary. The output for every command is displayed in the terminal for a simple evaluation of test results.

To run elashell or elatests, first extract the distribution package created previously and enter the extracted folder. Then, change directory to the 'bin' folder.

cd YOUR-DISTRIBUTION-PACKAGE-PATH/bin

Run Elashell:

./elashell

Available commands in the shell can be listed by using the command help. Specific command usage descriptions can be displayed by using help [Command] where [Command] must be replaced with the specific command name. For the entire command list please see the COMMANDS.md file.

Or run Elatests:

./elatests

Build on MacOS Host

1. Brief introduction

Both macOS (x86_64) and macOS (ARM64) are supported.

On macOS, besides the compilation for the host itself, cross-compilation is possible for the following targets:

• Android with architectures of armv7a, arm64 and simulators of x86/x86_64 are supported.
• iOS platforms to run on iPhone-arm64 and iPhoneSimulator-x86_64.

2. Install Pre-Requirements

The following packages related to configure and cmake must be installed on the host before compilation either by installation through the package manager homebrew or by building from source:

Note: Homebrew can be downloaded from Homebrew web site.

Install packages with Homebrew:

brew install autoconf automake libtool shtool pkg-config gettext cmake

Please note that homebrew has an issue with linking gettext. If you have an issue with the execution of autopoint, fix it by running:

brew link --force gettext

Download this repository using Git:

git clone https://github.com/elastos/Elastos.NET.Carrier.Native.SDK

3. Build to run on host

To compile the project from source code for the target to run on MacOS, carry out the following steps:

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir macos-$(uname -m)
cd macos-$(uname -m)

Generate the Makefile in the current directory:

Note: Please see custom options below.

cmake ../..

---

Optional (Generate the Makefile): To be able to build a distribution with a specific build type Debug/Release, as well as with customized install location of distributions, run the following commands:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=YOUR-INSTALL-PATH ../..

---

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program:

Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

4. Run Elashell or Elatests

Elashell is a fully functional, lightweight shell program that processes commands and returns the output to the terminal. Through Elashell, users may connect to other carrier nodes and exchange messages.

Elatests is also a shell program, but with predefined commands, therefore no user interaction is necessary. The output for every command is displayed in the terminal for a simple evaluation of test results.

To run elashell or elatests, first extract the distribution package created previously and enter the extracted folder. Then, change directory to the 'bin' folder.

cd YOUR-DISTRIBUTION-PACKAGE-PATH/bin

Run Elashell:

./elashell

Available commands in the shell can be listed by using the command help. Specific command usage descriptions can be displayed by using help [Command] where [Command] must be replaced with the specific command name. For the entire command list please see the COMMANDS.md file.

Or run Elatests:

./elatests

5. Cross-compilation for Android Platform

Elastos Carrier cmake system also supports to build cross-compilation for android platform on macOS with android NDK toolchains of same requirement of minimum API level 21.

With CMake, Elastos Carrier can be cross-compiled to run on Android as a target platform, while compilation is carried out on MacOS host.

Prerequisite: Android NDK 'android-ndk-r16b' or higher is required for macOS (x86_64). Android NDK 'android-ndk-r17c' or higher is required for macOS (ARM64). Android NDKs (such as 'android-ndk-r18b-darwin-x86_64' for MacOS Host) can be downloaded from Android developer web site. Please make sure to extract the downloaded NDK.

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir android
cd android

To generate the required Makefile in the current directory, please make sure to first replace 'YOUR-TARGET-ARCHITECTURE' and 'YOUR-ANDROID-NDK-HOME' with the correct option and path.

-DANDROID_ABI accepts the following target architecture options:

• armeabi-v7a
• arm64-v8a
• x86
• x86_64

Replace 'YOUR-ANDROID-NDK-HOME' with the path to the extracted NDK folder.

Run the command with the correct options described above:

cmake -DANDROID_ABI=YOUR-TARGET-ARCHITECTURE -DANDROID_NDK_HOME=YOUR-ANDROID-NDK-HOME -DCMAKE_TOOLCHAIN_FILE=../../cmake/AndroidToolchain.cmake ../..

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program:

Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

6. Cross-compilation for iOS Platform

With CMake, Elastos Carrier can be cross-compiled to run on iOS as a target platform, while compilation is carried out on a MacOS host with XCode.

Prerequisite: MacOS version must be 9.0 or higher.

Open a new terminal window.

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir ios
cd ios

To generate the required Makefile in the current directory, please make sure to first replace 'YOUR-IOS-PLATFORM' with the correct option.

-DIOS_PLATFORM accepts the following target architecture options:

• iphoneos
• iphonesimulator

Replace 'YOUR-IOS-PLATFORM' with the path to the extracted NDK folder.

Run the command with the correct options described above:

cmake -DIOS_PLATFORM=YOUR-IOS-PLATFORM -DCMAKE_TOOLCHAIN_FILE=../../cmake/iOSToolchain.cmake ../..

Build the program:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

make

Install the program:

Note: If "make install" fails due to missing permissions, use "sudo make install" instead.

make install

Create distribution package:

Note: If "make dist" fails due to missing permissions, use "sudo make dist" instead.

make dist

Build on Windows Host

1. Brief introduction

With CMake, Elastos Carrier can be cross-compiled to run only on Windows as target platform, while compilation is carried out on a Windows host. Both 32-bit and 64-bit target versions are supported.

2. Set up Environment

Prerequisites:

• Visual Studio IDE is required. The Community version can be downloaded at Visual Studio downloads for free.
• Download and install "Visual Studio Command Prompt (devCmd)" from Visual Studio Marketplace.
• Install 'Desktop development with C++' Workload

Start the program 'Visual Studio Installer'.

---

Alternative: Start Visual Studio IDE. In the menu, go to "Tools >> Get Tools and Features", it will open the Visual Studio Installer.

---

Make sure 'Desktop development with C++' Workload is installed.

On the right side, make sure in the 'Installation details' all of the following are installed:

• "Windows 8.1 SDK and UCRT SDK" <- might have to be selected additionally
• "Windows 10 SDK (10.0.17134.0)" <- might have to be selected additionally
• "VC++ 2017 version 15.9 ... tools"
• "C++ Profiling tools"
• "Visual C++ tools for CMake"
• "Visual C++ ATL for x86 and x64"

Additional tools are optional, some additional ones are installed by default with the Workload.

After modifications, restarting of Visual Studio might be required.

3. Build to run on host

To compile the project from source code for the target to run on Windows, carry out the following steps:

In Visual Studio, open Visual Studio Command Prompt from the menu "Tools >> Visual Studio Command Prompt". It will open a new terminal window.

---

Note: To build for a 32-bit target , select x86 Native Tools Command Console to run building commands, otherwise, select x64 Native Tools Command Console for a 64-bit target.

---

Get Visual Studio SDK and ToolSet version on the target platform.

cd tools\win
cmake .

Show information as follow:

================================
CMake command line for Windows:
cmake -G "NMake Makefiles" -DCMAKE_VS_PLATFORM_TOOLSET=YOUR-TOOLSET-VERSION -DCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION=YOUR-VSSDK-VERSION ...
================================

Navigate to the previously downloaded folder that contains the source code of the Carrier project.

cd YOUR-PATH/Elastos.NET.Carrier.Native.SDK

Enter the 'build' folder.

cd build

Create a new folder with the target platform name, then change directory.

mkdir win
cd win

Generate the Makefile in the current directory:

cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=outputs -DCMAKE_VS_PLATFORM_TOOLSET=YOUR-TOOLSET-VERSION -DCMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION=YOUR-VSSDK-VERSION ..\..

Build the program:

nmake

Install the program:

nmake install

Create distribution package:

nmake dist

4. Run Elashell or Elatests

Elashell is a fully functional, lightweight shell program that processes commands and returns the output to the terminal. Through Elashell, users may connect to other carrier nodes and exchange messages.

Elatests is also a shell program, but with predefined commands, therefore no user interaction is necessary. The output for every command is displayed in the terminal for a simple evaluation of test results.

To run elashell or elatests, first extract the distribution package created previously and enter the extracted folder. Then, change directory to the 'bin' folder.

cd YOUR-DISTRIBUTION-PACKAGE-PATH\bin

Run Elashell:

Make sure to replace 'YOUR-DISTRIBUTION-PACKAGE-PATH'.

elashell --config=YOUR-DISTRIBUTION-PACKAGE-PATH\etc\carrier\elashell.conf

Available commands in the shell can be listed by using the command help. Specific command usage descriptions can be displayed by using help [Command] where [Command] must be replaced with the specific command name. For the entire command list please see the COMMANDS.md file.

Or run Elatests:

Make sure to replace 'YOUR-DISTRIBUTION-PACKAGE-PATH'.

elatests --config=YOUR-DISTRIBUTION-PACKAGE-PATH\etc\carrier\elashell.conf

Build API Documentation

Currently, the API documentation can only be built on Linux hosts. MacOS has a bug issue with python, which would cause build process failure.

Build on Ubuntu / Debian / Linux Host

1. Install Pre-Requirements

sudo apt-get update
sudo apt-get install doxygen python-sphinx graphviz
curl -L -o /tmp/get-pip.py https://bootstrap.pypa.io/get-pip.py
sudo python /tmp/get-pip.py
sudo pip install breathe

2. Build

Change to the directory where the build for any target has been previously executed. For example, if the target was Linux, the folder structure would be similar to:

cd /YOUR-PATH/Elastos.NET.Carrier.Native.SDK/build/linux

Run the following command:

Note: If "make" fails due to missing permissions, use "sudo make" instead.

cmake -DENABLE_DOCS=ON ../..
make

3. View

The generated API documentation will be created in the new /docs directory on the same directory level.

Change to the docs folder:

cd docs/html

Open the index.html file in a browser from the terminal:

xdg-open index.html

Contribution

We welcome contributions to the Elastos Carrier Project.

Acknowledgments

A sincere thank you to all teams and projects that we rely on directly or indirectly.

License

This project is licensed under the terms of the GPLv3 license.