README.md

   1 `json-c`                       {#mainpage}
   2 ========
   3
   4 1. [Overview and Build Status](#overview)
   5 2. [Building on Unix](#buildunix)
   6 3. [Install Prerequisites](#installprereq)
   7 4. [Building with partial threading support](#buildthreaded)
   8 5. [Linking to libjson-c](#linking)
   9 6. [Using json-c](#using)
  10
  11 JSON-C - A JSON implementation in C <a name="overview"></a>
  12 -----------------------------------
  13
  14 Build Status
  15 * [AppVeyor Build](https://ci.appveyor.com/project/hawicz/json-c) ![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/json-c/json-c?branch=master&svg=true)
  16 * [Travis Build](https://travis-ci.org/json-c/json-c) ![Travis Build Status](https://travis-ci.org/json-c/json-c.svg?branch=master)
  17
  18 JSON-C implements a reference counting object model that allows you to easily
  19 construct JSON objects in C, output them as JSON formatted strings and parse
  20 JSON formatted strings back into the C representation of JSON objects.
  21 It aims to conform to [RFC 7159](https://tools.ietf.org/html/rfc7159).
  22
  23
  24 Building on Unix with `git`, `gcc` and `autotools` <a name="buildunix"></a>
  25 --------------------------------------------------
  26
  27 Home page for json-c: https://github.com/json-c/json-c/wiki
  28
  29 ### Prerequisites:
  30
  31 See also the "Installing prerequisites" section below.
  32
  33  - `gcc`, `clang`, or another C compiler
  34  - `libtool>=2.2.6b`
  35
  36 If you're not using a release tarball, you'll also need:
  37
  38  - `autoconf>=2.64` (`autoreconf`)
  39  - `automake>=1.13`
  40
  41 Make sure you have a complete `libtool` install, including `libtoolize`.
  42
  43 To generate docs (e.g. as part of make distcheck) you'll also need:
  44  - `doxygen>=1.8.13`
  45
  46 ### Build instructions:
  47
  48 `json-c` GitHub repo: https://github.com/json-c/json-c
  49
  50 ```sh
  51 $ git clone https://github.com/json-c/json-c.git
  52 $ cd json-c
  53 $ sh autogen.sh
  54 ```
  55
  56 followed by
  57
  58 ```sh
  59 $ ./configure  # --enable-threading
  60 $ make
  61 $ make install
  62 ```
  63
  64 To build and run the test programs:
  65
  66 ```sh
  67 $ make check
  68 $ make USE_VALGRIND=0 check   # optionally skip using valgrind
  69 ```
  70
  71 Install prerequisites <a name="installprereq"></a>
  72 -----------------------
  73
  74 If you are on a relatively modern system, you'll likely be able to install
  75 the prerequisites using your OS's packaging system.
  76
  77 ### Install using apt (e.g. Ubuntu 16.04.2 LTS)
  78 ```sh
  79 sudo apt install git
  80 sudo apt install autoconf automake libtool
  81 sudo apt install valgrind # optional
  82 ```
  83
  84 Then start from the "git clone" command, above.
  85
  86 ### Manually install and build autoconf, automake and libtool
  87
  88 For older OS's that don't have up-to-date version of the packages will
  89 require a bit more work. For example, CentOS release 5.11, etc...
  90
  91 ```sh
  92 curl -O http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz
  93 curl -O http://ftp.gnu.org/gnu/automake/automake-1.15.tar.gz
  94 curl -O http://ftp.gnu.org/gnu/libtool/libtool-2.2.6b.tar.gz
  95
  96 tar xzf autoconf-2.69.tar.gz
  97 tar xzf automake-1.15.tar.gz
  98 tar xzf libtool-2.2.6b.tar.gz
  99
 100 export PATH=${HOME}/ac_install/bin:$PATH
 101
 102 (cd autoconf-2.69 && \
 103   ./configure --prefix ${HOME}/ac_install && \
 104   make && \
 105   make install)
 106
 107 (cd automake-1.15 && \
 108   ./configure --prefix ${HOME}/ac_install && \
 109   make && \
 110   make install)
 111
 112 (cd libtool-2.2.6b && \
 113   ./configure --prefix ${HOME}/ac_install && \
 114   make && \
 115   make install)
 116 ```
 117
 118
 119 Building with partial threading support <a name="buildthreaded"></a>
 120 ----------------------------------------
 121
 122 Although json-c does not support fully multi-threaded access to
 123 object trees, it has some code to help make use in threaded programs
 124 a bit safer.  Currently, this is limited to using atomic operations for
 125 json_object_get() and json_object_put().
 126
 127 Since this may have a performance impact, of at least 3x slower
 128 according to https://stackoverflow.com/a/11609063, it is disabled by
 129 default.  You may turn it on by adjusting your configure command with:
 130    --enable-threading
 131
 132 Separately, the default hash function used for object field keys,
 133 lh_char_hash, uses a compare-and-swap operation to ensure the randomly
 134 seed is only generated once.  Because this is a one-time operation, it
 135 is always compiled in when the compare-and-swap operation is available.
 136
 137
 138 Linking to `libjson-c` <a name="linking">
 139 ----------------------
 140
 141 If your system has `pkgconfig`,
 142 then you can just add this to your `makefile`:
 143
 144 ```make
 145 CFLAGS += $(shell pkg-config --cflags json-c)
 146 LDFLAGS += $(shell pkg-config --libs json-c)
 147 ```
 148
 149 Without `pkgconfig`, you would do something like this:
 150
 151 ```make
 152 JSON_C_DIR=/path/to/json_c/install
 153 CFLAGS += -I$(JSON_C_DIR)/include/json-c
 154 LDFLAGS+= -L$(JSON_C_DIR)/lib -ljson-c
 155 ```
 156
 157
 158 Using json-c <a name="using">
 159 ------------
 160
 161 To use json-c you can either include json.h, or preferrably, one of the
 162 following more specific header files:
 163
 164 * json_object.h  - Core types and methods.
 165 * json_tokener.h - Methods for parsing and serializing json-c object trees.
 166 * json_pointer.h - JSON Pointer (RFC 6901) implementation for retrieving
 167                    objects from a json-c object tree.
 168 * json_object_iterator.h - Methods for iterating over single json_object instances.
 169 * json_visit.h   - Methods for walking a tree of json-c objects.
 170 * json_util.h    - Miscelleanous utility functions.
 171
 172 For a full list of headers see [files.html](files.html)
 173