README

PyCCN - CCN bindings for Python

This is intended to be a rather "thin" implementation, which supports Python
objects corresponding to the major CCNx entities - Interest, ContentObject, and
so on, as well as some support objects.  The C code is mostly just responsible
for marshaling data back and forth between the formats, though there are some
useful functions for key generation/access included.

These are mapped more or less directly from the CCNx wire format, and the
Python objects are, in fact, backed by a cached version of the wire format
or native c object, a Python CObject kept in self.ccn_data. Accessing the
attribute regenerates this backing CObject if necessary - those mechanics
are in the Python code.

The Interest and ContentObject objects also cache their parsed versions
as well

=================================================
1. Build and install instructions
=================================================


1.1 GENERATING CONFIGURE FILE

This step should be already done for you, but if configure file is not present
you might need to perform following operations:

  mkdir build-aux
  autoreconf -i

or just run:

  ./bootstrap

Later when you fetch new version of files you can just simply use autoreconf
with no options.


1.2 DEPENDENCIES

- GNU automake 1.11
- GNU libtool (not sure of minimum version, using 2.2.6b)
- CCNx 0.4+
- OpenSSL (need to be linked to the same version used by libccn
- Python 2.7+ (tested with 2.7.0 and 3.2.1)

1.2 CONFIGURING AND BUILDING

Run ./configure script.

Relevant options:
* --with-ccn=DIR - path to CCNx distribution directory
* PYTHON=<python interpreter> - path to python interpreter you want to use
                                In some cases you might need to specify
                                LDFLAGS=-L/usr/lib
* PYTHON_SITE_PKG=<path> - custom path where pyccn should be installed
* OPENSSL_CRYPTO=<library> - full path to the library used by libccn
* OPENSSL_INCLUDES, OPENSSL_LDFLAGS, OPENSSL_LIBS - to override determined
                                                    values

Then do `make` to compile the code.


1.3 TESTING

To run tests for the suite:

  make check


1.4 INSTALLING

The package will be installed in site-packages of the selected python.

  make install

or

  make install-strip (to strip any debugging symbols)

==================================================
2. Using the Python bindings
==================================================

All of the files are contained inside of pyccn package. To use you can call:

  import pyccn

  or

  from pyccn import CCN, Name, Key, ... and so on ...

==================================================
3. Platform specific notes
==================================================

3.0 All platforms

- when configuring make sure you compile PyCCN with the same openssl library as
  you compiled CCNx with. To specify alternative version use
  --with-openssl=<openssl root dir>
  An sign of linking with wrong library is getting segment violation on
  signing.py testcase.

3.1 MacOS X

- when building python from sources you need to run ./configure --enable-shared
  otherwise you might experience crash with message:
  "Fatal Python error: PyThreadState_Get: no current thread"
  when trying to import pyccn. I'm looking into ways to make code also work
  when python is statically compiled.

- On MacOS X 10.7 (Lion) while compiling the module you'll get bunch of
  warnings about openssl functions being deprecatead. This is ok. The message
  is because Apple decided to replace openssl with their own implementation
  called Common Crypto and want to discourage developers from using OpenSSL.
  If you don't want to see the warnings you might want to point to alternative
  version (e.g. from Mac Ports) using OPENSSL_* variables.  Remember that you
  need to compile PyCCN with the same version of OpenSSL that you compiled CCNx
  otherwise PyCCN will crash when trying to sign Content Objects.