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 (including MinGW)
  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, the build system 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 Jansson can be built with Visual Studio 2010 (and probably newer
  61 versions, too). The solution and project files are in the
  62 ``win32/vs2010/`` directory in the source distribution.
  63
  64
  65 Other Systems
  66 -------------
  67
  68 On non Unix-like systems, you may be unable to run the ``./configure``
  69 script. In this case, follow these steps. All the files mentioned can
  70 be found in the ``src/`` directory.
  71
  72 1. Create ``jansson_config.h`` (which has some platform-specific
  73    parameters that are normally filled in by the ``./configure``
  74    script). Edit ``jansson_config.h.in``, replacing all ``@variable@``
  75    placeholders, and rename the file to ``jansson_config.h``.
  76
  77 2. Make ``jansson.h`` and ``jansson_config.h`` available to the
  78    compiler, so that they can be found when compiling programs that
  79    use Jansson.
  80
  81 3. Compile all the ``.c`` files (in the ``src/`` directory) into a
  82    library file. Make the library available to the compiler, as in
  83    step 2.
  84
  85
  86 Building the Documentation
  87 --------------------------
  88
  89 (This subsection describes how to build the HTML documentation you are
  90 currently reading, so it can be safely skipped.)
  91
  92 Documentation is in the ``doc/`` subdirectory. It's written in
  93 reStructuredText_ with Sphinx_ annotations. To generate the HTML
  94 documentation, invoke::
  95
  96    make html
  97
  98 and point your browser to ``doc/_build/html/index.html``. Sphinx_ 1.0
  99 or newer is required to generate the documentation.
 100
 101 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 102 .. _Sphinx: http://sphinx.pocoo.org/
 103
 104
 105 Compiling Programs that Use Jansson
 106 ===================================
 107
 108 Jansson involves one C header file, :file:`jansson.h`, so it's enough
 109 to put the line
 110
 111 ::
 112
 113     #include <jansson.h>
 114
 115 in the beginning of every source file that uses Jansson.
 116
 117 There's also just one library to link with, ``libjansson``. Compile and
 118 link the program as follows::
 119
 120     cc -o prog prog.c -ljansson
 121
 122 Starting from version 1.2, there's also support for pkg-config_::
 123
 124     cc -o prog prog.c `pkg-config --cflags --libs jansson`
 125
 126 .. _pkg-config: http://pkg-config.freedesktop.org/