Permalink
Browse files

Add sphinx docs

  • Loading branch information...
petya2164 committed Oct 5, 2018
1 parent 3a27c34 commit 0248ac432c531e2fa5be1e5234695f9041905f69
@@ -57,7 +57,6 @@ local.properties
*.sdf
*.opensdf
*.log
*.txt
*.vcxproj*
VSProjects
@@ -1,26 +1,10 @@
License
-------
A valid Kodo license is required if you wish to use this project.
Please request a license by **filling out the license request** form_.
Kodo is available under a research- and education-friendly license,
you can see the details here_.
If you try to configure without a valid license, then you will get an error!
.. _form: http://steinwurf.com/license/
.. _here: http://steinwurf.com/research-license/
About
-----
This repository contains high-level C bindings for the Kodo RLNC erasure coding
This kodo-rlnc-c contains high-level C bindings for the Kodo RLNC erasure coding
library. The bindings provide access to the basic functionality provided by
Kodo RLNC, such as encoding and decoding data. The examples folder provides
Kodo RLNC, such as encoding and decoding data. The ``examples`` folder provides
sample applications that demonstrate the usage of the C API.
The kodo-rlnc-c repository: https://github.com/steinwurf/kodo-rlnc-c
.. image:: http://buildbot.steinwurf.dk/svgstatus?project=kodo-rlnc-c
:target: http://buildbot.steinwurf.dk/powerconsole?project=kodo-rlnc-c
@@ -29,16 +13,29 @@ us at our developer mailing list (hosted at Google Groups):
* http://groups.google.com/group/steinwurf-dev
License
-------
To obtain a valid Kodo license **you must fill out the license request** form_.
Kodo is available under a research- and education-friendly license, see the
details in the LICENSE.rst file.
.. _form: http://steinwurf.com/license/
Documentation
-------------
To get started, see the manual here:
Please read our general documentation here to get started:
http://docs.steinwurf.com
The kodo-rlnc documentation is located here:
http://docs.steinwurf.com/kodo-rlnc-c/master/index.html
Quick Start
-----------
If you already installed a C++11 compiler, git and python on your system,
If you already installed a C++14 compiler, git and python on your system,
then you can clone this repository to a suitable folder::
git clone git@github.com:steinwurf/kodo-rlnc-c.git
@@ -0,0 +1,11 @@
===
API
===
Overview of the public API.
.. toctree::
:maxdepth: 2
encoder
decoder
@@ -0,0 +1,6 @@
Decoder API
===========
.. literalinclude:: /../src/kodo_rlnc_c/decoder.h
:language: c
:linenos:
@@ -0,0 +1,6 @@
Encoder API
===========
.. literalinclude:: /../src/kodo_rlnc_c/encoder.h
:language: c
:linenos:
@@ -0,0 +1,115 @@
# -*- coding: utf-8 -*-
# -- General configuration ------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'guzzle_sphinx_theme',
'wurfapi',
]
# wurfapi options - relative to your docs dir
wurfapi = {
'source_paths': [
'../src/kodo_rlnc_c/encoder.h',
'../src/kodo_rlnc_c/decoder.h',
],
'recursive': False,
'parser': {
'type': 'doxygen',
'download': True,
'warnings_as_error': True,
}
}
# Add any paths that contain templates here, relative to this directory.
templates_path = []
# The suffix(es) of source filenames
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Kodo-RLNC-C'
copyright = u'2018, Steinwurf'
author = u'Steinwurf'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u''
# The full version, including alpha/beta/rc tags.
release = u''
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output ----------------------------------------------
try:
import guzzle_sphinx_theme
html_theme = 'guzzle_sphinx_theme'
html_theme_path = guzzle_sphinx_theme.html_theme_path()
except ImportError:
print("Unable to import the used theme.\n"
"Please install requirements.txt before building")
pass
html_sidebars = {
'**': [
'logo.html', 'logo-text.html', 'globaltoc.html', 'searchbox.html',
'versions.html'
]
}
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
"version_json_location": "versjon.json"
}
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = '../kodo-rlnc.svg'
# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []
# If true, the reST sources are included in the HTML build as _sources/name
html_copy_source = False
# If true, links to the reST sources are added to the pages.
html_show_sourcelink = False
@@ -0,0 +1,12 @@
Encode Decode On-the-fly
========================
This example shows how to to perform on-the-fly encoding. The encoder
can start to generate encoded packets from a block before all symbols
are specified. This can be useful when the symbols are produced on-the-fly.
The complete example code is shown below.
.. literalinclude:: /../examples/encode_decode_on_the_fly/encode_decode_on_the_fly.c
:language: c
:linenos:
@@ -0,0 +1,10 @@
Encode Decode Simple
====================
This example shows how to encode and decode a block of memory.
The complete example code is shown below.
.. literalinclude:: /../examples/encode_decode_simple/encode_decode_simple.c
:language: c
:linenos:
@@ -0,0 +1,10 @@
========
Examples
========
.. toctree::
:maxdepth: 2
encode_decode_simple
encode_decode_on_the_fly
udp_sender_receiver
@@ -0,0 +1,30 @@
UDP Sender&Receiver
===================
This pair of examples shows how to encode and transmit some random data over
a UDP socket, then receive and decode that data at the other end.
The sender and receiver applications are standalone, and you can run them on
the same computer or over an actual IP network.
Note that the receiver should be started **before** the sender!
.. contents:: Table of Contents
:local:
The sender application
----------------------
The example code for the sender is shown below.
.. literalinclude:: /../examples/udp_sender_receiver/udp_sender.c
:language: c
:linenos:
The receiver application
------------------------
The example code for the receiver is shown below.
.. literalinclude:: /../examples/udp_sender_receiver/udp_receiver.c
:language: c
:linenos:
@@ -0,0 +1,104 @@
.. _including_kodo_rlnc_c:
Including kodo-rlnc-c in Your Application
=========================================
This guide shows how to include kodo-rlnc-c in your application.
First of all, you need to build kodo-rln-c following the
:ref:`quick_start_kodo_rlnc_c` guide. If you want to cross-compile for your
target platform (e.g. Android, iOS, Raspberry Pi), please follow the
`Cross-compilation <http://docs.steinwurf.com/cross_compile.html>`_ guide.
In principle, you can use the library with any build system. Basically,
you can choose between the shared library and the static library.
Shared Library
--------------
In many cases, it is easier to include kodo-rlnc-c as a *shared* library in
your application. With the following command, you can copy the compiled
shared library to the target folder specified by the ``install_path`` option.
In this example, we will create the ``shared_test`` folder for this purpose::
python waf install --install_shared_libs --install_path="./shared_test"
The kodo-rlnc-c shared library is called ``libkodo_rlnc_c.so`` on Linux,
``kodo_rlnc_c.dll`` on Windows and ``libkodo_rlnc_c.dylib`` on Mac OSX.
You can link with this shared library using your own build system.
You also need to include the ``encoder.h`` or ``decoder.h`` header files
that are installed to the ``include`` folder within the specified
``install_path``.
Now we copy an existing kodo-rlnc-c example (encode_decode_simple) to the
``shared_test`` folder and we compile it to a binary called ``myapp``::
cp examples/encode_decode_simple/encode_decode_simple.c shared_test/myapp.c
cd shared_test
The following command demonstrates the necessary flags for the gcc/g++ compiler
(other compilers require similar settings)::
gcc myapp.c -o myapp -I./include -L. -Wl,-Bdynamic -lkodo_rlnc_c -lstdc++ \
-Wl,-rpath .
In practice, you should set the ``-I`` and ``-L`` flags to the path where you
installed the shared library.
Now you should be able to run the new binary::
./myapp
If you dynamically link your application with the shared library, then you
have to copy the shared library to a folder where your system can find it
when you execute your application. On Windows, you typically place the DLL
in the same folder as your executable. On Unix systems, you can set the
``rpath`` of your executable or you can adjust ``LD_LIBRARY_PATH`` to include
the path where you installed the shared library.
Static Library
--------------
After building kodo-rlnc-c, you can install the static libraries to your target
folder with the following command (the ``install_path`` option specifies
the target folder which will be ``static_test`` in this example)::
python waf install --install_static_libs --install_path="./static_test"
The kodo-rlnc-c static library is called ``libkodo_rlnc_c_static.a`` on Linux
and Mac and ``kodo_rlnc_c_static.lib`` on Windows. The install command also
installs the static libraries from the kodo-rlnc-c dependencies (you will need
the ``kodo_rlnc``, ``fifi`` and ``cpuid`` libraries as well).
You can link with these static libraries using your own build system. Of course,
you will need to include ``encoder.h`` or ``decoder.h`` in your code (which
are installed to the ``include`` folder within the specified ``install_path``).
Now we copy an existing kodo-rlnc-c example (encode_decode_simple) to the
``static_test`` folder and we compile it to a binary called ``myapp``::
cp examples/encode_decode_simple/encode_decode_simple.c static_test/myapp.c
cd static_test
The following command demonstrates the necessary flags for the gcc/g++ compiler
(other compilers require similar settings)::
gcc myapp.c -o myapp -I./include -Wl,-Bstatic -L. -lkodo_rlnc_c_static \
-lkodo_rlnc -lfifi -lcpuid -Wl,-Bdynamic -lm -lstdc++
In practice, you should set the ``-I`` and ``-L`` flags to the path where you
installed the static libraries.
Now you should be able to run the new binary (note that this binary will
be quite large, since it includes all the static libraries)::
./myapp
It is important to note that you need to link with the C++ standard library
(by using ``-lstdc++`` above), because the kodo-rlnc-c library actually wraps a
C++ library (kodo) that uses the C++ standard library. However, you can omit
this flag if you link your application with g++ instead of gcc (g++
automatically includes the stdc++ library)::
g++ myapp.c -o myapp -I./include -Wl,-Bstatic -L. -lkodo_rlnc_c_static \
-lkodo_rlnc -lfifi -lcpuid -Wl,-Bdynamic
Oops, something went wrong.

0 comments on commit 0248ac4

Please sign in to comment.