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 Unix-like systems
  14 -----------------
  15
  16 Unpack the source tarball and change to the source directory:
  17
  18 .. parsed-literal::
  19
  20     bunzip2 -c jansson-|release|.tar.bz2 | tar xf -
  21     cd jansson-|release|
  22
  23 The source uses GNU Autotools (autoconf_, automake_, libtool_), so
  24 compiling and installing is extremely simple::
  25
  26     ./configure
  27     make
  28     make check
  29     make install
  30
  31 To change the destination directory (``/usr/local`` by default), use
  32 the ``--prefix=DIR`` argument to ``./configure``. See ``./configure
  33 --help`` for the list of all possible installation options. (There are
  34 no options to customize the resulting Jansson binary.)
  35
  36 The command ``make check`` runs the test suite distributed with
  37 Jansson. This step is not strictly necessary, but it may find possible
  38 problems that Jansson has on your platform. If any problems are found,
  39 please report them.
  40
  41 If you obtained the source from a Git repository (or any other source
  42 control system), there's no ``./configure`` script as it's not kept in
  43 version control. To create the script, Autotools needs to be
  44 bootstrapped. There are many ways to do this, but the easiest one is
  45 to use ``autoreconf``::
  46
  47     autoreconf -vi
  48
  49 This command creates the ``./configure`` script, which can then be
  50 used as described above.
  51
  52 .. _autoconf: http://www.gnu.org/software/autoconf/
  53 .. _automake: http://www.gnu.org/software/automake/
  54 .. _libtool: http://www.gnu.org/software/libtool/
  55
  56
  57 Windows
  58 -------
  59
  60 On Windows (and other non-Unix-like systems), you may be unable to run
  61 the ``./configure`` script. In this case, follow these steps. All the
  62 files mentioned can be found in the ``src/`` directory.
  63
  64 1. Rename ``jansson_config.h.win32`` to ``jansson_config.h``. This
  65    file has some platform-specific parameters that are normally filled
  66    in by the ``./configure`` script.
  67
  68 2. Make ``jansson.h`` and ``jansson_config.h`` available to the
  69    compiler, so that they can be found when compiling programs that
  70    use Jansson.
  71
  72 3. Compile all the ``.c`` files (in the ``src/`` directory) into a
  73    library file. Make the library available to the compiler, as in
  74    step 2.
  75
  76
  77 Installing Prebuilt Binary Packages
  78 -----------------------------------
  79
  80 Binary ``.deb`` packages for Ubuntu Linux are available in `this PPA`_
  81 at Launchpad_. Follow the instructions in the PPA ("Technical details
  82 about this PPA" link) to take the PPA into use. Then install the -dev
  83 package::
  84
  85   sudo apt-get install libjansson-dev
  86
  87 .. _this PPA: http://launchpad.net/~petri/+archive/ppa
  88 .. _Launchpad: http://launchpad.net/
  89
  90
  91 Building the Documentation
  92 --------------------------
  93
  94 (This subsection describes how to build the HTML documentation you are
  95 currently reading, so it can be safely skipped.)
  96
  97 Documentation is in the ``doc/`` subdirectory. It's written in
  98 reStructuredText_ with Sphinx_ annotations. To generate the HTML
  99 documentation, invoke::
 100
 101    make html
 102
 103 and point your browser to ``doc/_build/html/index.html``. Sphinx_ is
 104 required to generate the documentation.
 105
 106 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 107 .. _Sphinx: http://sphinx.pocoo.org/
 108
 109
 110 Compiling Programs That Use Jansson
 111 ===================================
 112
 113 Jansson involves one C header file, :file:`jansson.h`, so it's enough
 114 to put the line
 115
 116 ::
 117
 118     #include <jansson.h>
 119
 120 in the beginning of every source file that uses Jansson.
 121
 122 There's also just one library to link with, ``libjansson``. Compile and
 123 link the program as follows::
 124
 125     cc -o prog prog.c -ljansson
 126
 127 Starting from version 1.2, there's also support for pkg-config_::
 128
 129     cc -o prog prog.c `pkg-config --cflags --libs jansson`
 130
 131 .. _pkg-config: http://pkg-config.freedesktop.org/