doc/gettingstarted.rst

   1 ***************
   2 Getting Started
   3 ***************
   4
   5 .. highlight:: c
   6
   7 Compiling and Installing Jansson
   8 ================================
   9
  10 The Jansson source is available at
  11 http://www.digip.org/jansson/releases/.
  12
  13 Unpack the source tarball and change to the source directory:
  14
  15 .. parsed-literal::
  16
  17     bunzip2 -c jansson-|release|.tar.bz2 | tar xf -
  18     cd jansson-|release|
  19
  20 The source uses GNU Autotools (autoconf_, automake_, libtool_), so
  21 compiling and installing is extremely simple::
  22
  23     ./configure
  24     make
  25     make check
  26     make install
  27
  28 To change the destination directory (``/usr/local`` by default), use
  29 the ``--prefix=DIR`` argument to ``./configure``. See ``./configure
  30 --help`` for the list of all possible installation options. (There are
  31 no options to customize the resulting Jansson binary.)
  32
  33 The command ``make check`` runs the test suite distributed with
  34 Jansson. Python_ is required to run the tests. This step is not
  35 strictly necessary, but it may find possible problems that Jansson has
  36 on your platform. If any problems are found, please report them.
  37
  38 If you obtained the source from a Git repository (or any other source
  39 control system), there's no ``./configure`` script as it's not kept in
  40 version control. To create the script, Autotools needs to be
  41 bootstrapped. There are many ways to do this, but the easiest one is
  42 to use ``autoreconf``::
  43
  44     autoreconf -vi
  45
  46 This command creates the ``./configure`` script, which can then be
  47 used as described in the previous section.
  48
  49 .. _autoconf: http://www.gnu.org/software/autoconf/
  50 .. _automake: http://www.gnu.org/software/automake/
  51 .. _libtool: http://www.gnu.org/software/libtool/
  52 .. _Python: http://www.python.org/
  53
  54
  55 Installing Prebuilt Binary Packages
  56 -----------------------------------
  57
  58 Binary ``.deb`` packages for Ubuntu are available in `this PPA`_ at
  59 Launchpad_. Follow the instructions in the PPA ("Technical details
  60 about this PPA" link) to take the PPA into use. Then install the -dev
  61 package::
  62
  63   sudo apt-get install libjansson-dev
  64
  65 .. _this PPA: http://launchpad.net/~petri/+archive/ppa
  66 .. _Launchpad: http://launchpad.net/
  67
  68
  69 Building the Documentation
  70 --------------------------
  71
  72 (This subsection describes how to build the HTML documentation you are
  73 currently reading, so it can be safely skipped.)
  74
  75 Documentation is in the ``doc/`` subdirectory. It's written in
  76 reStructuredText_ with Sphinx_ annotations. To generate the HTML
  77 documentation, invoke::
  78
  79    make html
  80
  81 and point your browser to ``doc/_build/html/index.html``. Sphinx_ is
  82 required to generate the documentation.
  83
  84 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  85 .. _Sphinx: http://sphinx.pocoo.org/
  86
  87
  88 Compiling Programs Using Jansson
  89 ================================
  90
  91 Jansson involves one C header file, :file:`jansson.h`, so it's enough
  92 to put the line
  93
  94 ::
  95
  96     #include <jansson.h>
  97
  98 in the beginning of every source file that uses Jansson.
  99
 100 There's also just one library to link with, ``libjansson``. Compile and
 101 link the program as follows::
 102
 103     cc -o prog prog.c -ljansson