From 56e29ea01914681f394e3a0af4169936079858a7 Mon Sep 17 00:00:00 2001
From: Luca Muscariello <muscariello@ieee.org>
Date: Wed, 12 Feb 2020 13:49:52 +0100
Subject: [HICN-512] documentation bundle using sphinx

Change-Id: I1dcbca50f7406ef2714683547b6bb32463e1baf8
Signed-off-by: Luca Muscariello <muscariello@ieee.org>
---
 docs/source/lib.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/source/lib.md

(limited to 'docs/source/lib.md')

diff --git a/docs/source/lib.md b/docs/source/lib.md
new file mode 100644
index 000000000..58f23b510
--- /dev/null
+++ b/docs/source/lib.md
@@ -0,0 +1,116 @@
+
+The Hybrid ICN Core Library
+==============================
+
+## Introduction
+
+libhicn provides a support library coded in C designed to help developers embed
+Hybrid ICN (hICN) functionalities in their applications (eg. forwarder, socket
+API, etc.). Its purpose is to follow the hICN specification for which it
+provides a reference implementation, abstracting the user from all internal
+mechanisms, and offering an API independent of the packet format (eg. IPv4 or
+IPv6). The library is designed to be portable across both desktop and
+mobile platforms, and we currently aim at supporting Linux, Android, OSX and
+iOS, by writing the necessary adapters to realize hICN functionality in
+userspace according to the available APIs and permissions that each system
+offers.
+
+The library consists in several layers:
+- the core library (hicn.h) provides a standard hICN packet format, as well as
+an API allowing manipulation of packet headers;
+- an hICN helper, allowing an hICN stack to be built in userspace in a portable
+way, based on TUN devices and accessible though file descriptors;
+- a network layer allow the sending an receiving of hICN packets on those file
+descriptors, implementing both source and destination address translation as
+required by the hICN mechanisms;
+- finally, a "transport" API allows the forging of dummy interest and data
+packets.
+
+A commandline interface (hicnc) is also provided that uses the library and can
+for instance be used as a test traffic generator. This interface can be run as
+either a consumer, a producer, or a simple forwarder.
+
+## Folder content
+
+CMakeLists.txt          CMkake global build file
+doc                     Package documentation
+README.md               This file
+src
+    base.h		Base definitions for hICN implementation
+    CMakeLists.txt      CMake library build file
+    common.{h,c}	Harmonization layer across supported platforms
+    compat.{h,c}	Compatibility layer for former API
+    error.{h,c}		Error management files
+    header.h		hICN header definitions
+    hicn.h		Master include file
+    mapme.{h,c}		MAP-Me : anchorless producer mobility mechanisms 
+    name.{h,c}		hICN naming conventions and name processing + IP helpers
+    ops.{h,c}		Protocol-independent hICN operations
+    protocol/*		Protocol headers + protocol-dependent implementations
+    protocol.h		Common file for protocols
+
+## Using libhicn
+
+### Platforms ###
+
+libhicn has been tested in:
+
+- Ubuntu 16.04 LTS (x86_64)
+- Ubuntu 18.04 LTS (x86_64)
+- Debian Stable/Testing
+- Red Hat Enterprise Linux 7
+- CentOS 7
+- Android 8
+- iOS 12
+- macOS 10.12
+- Windows 10
+
+Other platforms and architectures may work.
+
+### Dependencies
+
+Build dependencies:
+
+- c11 ( clang / gcc )
+- CMake 3.4
+
+Basic dependencies: None
+
+## Installation
+
+You can either use released packages, or compile libhicn from sources.
+
+### Release mode
+
+mkdir build
+cd build
+cmake ..
+make
+sudo make install
+
+### Debug mode
+
+mkdir debug
+cd debug
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+make
+sudo make install
+
+## License
+
+This software is distributed under the following license:
+
+```
+Copyright (c) 2017-2019 Cisco and/or its affiliates.
+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.
+```
-- 
cgit 1.2.3-korg