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. This step is not strictly necessary, but it may find possible
  35 problems that Jansson has on your platform. If any problems are found,
  36 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 above.
  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
  53
  54 Installing Prebuilt Binary Packages
  55 -----------------------------------
  56
  57 Binary ``.deb`` packages for Ubuntu are available in `this PPA`_ at
  58 Launchpad_. Follow the instructions in the PPA ("Technical details
  59 about this PPA" link) to take the PPA into use. Then install the -dev
  60 package::
  61
  62   sudo apt-get install libjansson-dev
  63
  64 .. _this PPA: http://launchpad.net/~petri/+archive/ppa
  65 .. _Launchpad: http://launchpad.net/
  66
  67
  68 Building the Documentation
  69 --------------------------
  70
  71 (This subsection describes how to build the HTML documentation you are
  72 currently reading, so it can be safely skipped.)
  73
  74 Documentation is in the ``doc/`` subdirectory. It's written in
  75 reStructuredText_ with Sphinx_ annotations. To generate the HTML
  76 documentation, invoke::
  77
  78    make html
  79
  80 and point your browser to ``doc/_build/html/index.html``. Sphinx_ is
  81 required to generate the documentation.
  82
  83 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  84 .. _Sphinx: http://sphinx.pocoo.org/
  85
  86
  87 Compiling Programs That Use Jansson
  88 ===================================
  89
  90 Jansson involves one C header file, :file:`jansson.h`, so it's enough
  91 to put the line
  92
  93 ::
  94
  95     #include <jansson.h>
  96
  97 in the beginning of every source file that uses Jansson.
  98
  99 There's also just one library to link with, ``libjansson``. Compile and
 100 link the program as follows::
 101
 102     cc -o prog prog.c -ljansson
 103
 104 Starting from version 1.2, there's also support for pkg-config_::
 105
 106     cc -o prog prog.c `pkg-config --cflags --libs jansson`
 107
 108 .. _pkg-config: http://pkg-config.freedesktop.org/