Installation
============

**Requirements**
    * ``libelf`` [#]_ >= 0.8.13
    * ``Cython`` [#]_

Before trying to build, you should install the libelf library (see the link
above). If you tried
to build before installing libelf, run ``python setup.py clean --all`` and
try again.

Building :mod:`pylibelf` requires 
that you have ``Cython`` installed, because it is determined at build
time which ELF constants are available. You can install it using the usual
installation mechanisms, e.g., by downloading it manually and running
``python setup.py install``, or by doing ``pip install cython`` (requires
that you have pip [#]_ installed).


If you want to use :mod:`pylibelf` locally, run::
    
    ~/pylibelf $ python setup.py build_ext --inplace


If you want to install pylibelf system-wide, you can run::
    
    ~/pylibelf $ sudo python setup.py install


You should now be able to::

    import pylibelf


Running the tests (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To run the tests, you will have to compile a few test binaries and test
extensions. These are only build when you run ``build_ext`` with the
``--inplace`` option.
You must install ``nose`` [#]_, a test framework and test runner. Run::

    ~/pylibelf $ pip install nose
    ~/pylibelf $ python setup.py build_ext --inplace
    ~/pylibelf $ nosetests


Controlling the test files
""""""""""""""""""""""""""
By default the tests are performed on copies of the compiled samples, and
the executable pointed to by the ``SHELL`` environment variable 
(or :file:`/bin/bash` if not set). 
If you want to specify another executable that test suites should operate on, 
set the ``PYLIBELF_TESTFILE`` environment variable to the preferred executable
ELF file.
To run the ar-related tests on a different file than the sample one,
set the ``PYLIBELF_TESTFILE_AR`` environment variable to a static 
library archive (``.a``).


References
^^^^^^^^^^
.. [#] http://www.mr511.de/software/.
.. [#] http://cython.org/
.. [#] http://pypi.python.org/pypi/pip
.. [#] http://somethingaboutorange.com/mrl/projects/nose
