1*************** 2Getting Started 3*************** 4 5.. highlight:: c 6 7Compiling and Installing Jansson 8================================ 9 10The Jansson source is available at 11http://www.digip.org/jansson/releases/. 12 13Unix-like systems (including MinGW) 14----------------------------------- 15 16Unpack 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 23The source uses GNU Autotools (autoconf_, automake_, libtool_), so 24compiling and installing is extremely simple:: 25 26 ./configure 27 make 28 make check 29 make install 30 31To change the destination directory (``/usr/local`` by default), use 32the ``--prefix=DIR`` argument to ``./configure``. See ``./configure 33--help`` for the list of all possible installation options. (There are 34no options to customize the resulting Jansson binary.) 35 36The command ``make check`` runs the test suite distributed with 37Jansson. This step is not strictly necessary, but it may find possible 38problems that Jansson has on your platform. If any problems are found, 39please report them. 40 41If you obtained the source from a Git repository (or any other source 42control system), there's no ``./configure`` script as it's not kept in 43version control. To create the script, the build system needs to be 44bootstrapped. There are many ways to do this, but the easiest one is 45to use ``autoreconf``:: 46 47 autoreconf -vi 48 49This command creates the ``./configure`` script, which can then be 50used 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.. _build-cmake: 58 59CMake (various platforms, including Windows) 60-------------------------------------------- 61 62Jansson can be built using CMake_. Create a build directory for an 63out-of-tree build, change to that directory, and run ``cmake`` (or ``ccmake``, 64``cmake-gui``, or similar) to configure the project. 65 66See the examples below for more detailed information. 67 68.. note:: In the below examples ``..`` is used as an argument for ``cmake``. 69 This is simply the path to the jansson project root directory. 70 In the example it is assumed you've created a sub-directory ``build`` 71 and are using that. You could use any path you want. 72 73.. _build-cmake-unix: 74 75Unix (Make files) 76^^^^^^^^^^^^^^^^^ 77Generating make files on unix: 78 79.. parsed-literal:: 80 81 bunzip2 -c jansson-|release|.tar.bz2 | tar xf - 82 cd jansson-|release| 83 84 mkdir build 85 cd build 86 cmake .. # or `ccmake ..` for a GUI. 87 88Then to build:: 89 90 make 91 make check 92 make install 93 94Windows (Visual Studio) 95^^^^^^^^^^^^^^^^^^^^^^^ 96Creating Visual Studio project files from the command line: 97 98.. parsed-literal:: 99 100 <unpack> 101 cd jansson-|release| 102 103 md build 104 cd build 105 cmake -G "Visual Studio 10" .. 106 107You will now have a *Visual Studio Solution* in your build directory. 108To run the unit tests build the ``RUN_TESTS`` project. 109 110If you prefer a GUI the ``cmake`` line in the above example can 111be replaced with:: 112 113 cmake-gui .. 114 115For command line help (including a list of available generators) 116for CMake_ simply run:: 117 118 cmake 119 120To list available CMake_ settings (and what they are currently set to) 121for the project, run:: 122 123 cmake -LH .. 124 125Mac OSX (Xcode) 126^^^^^^^^^^^^^^^ 127If you prefer using Xcode instead of make files on OSX, 128do the following. (Use the same steps as 129for :ref:`Unix <build-cmake-unix>`):: 130 131 ... 132 cmake -G "Xcode" .. 133 134Additional CMake settings 135^^^^^^^^^^^^^^^^^^^^^^^^^ 136 137Shared library 138"""""""""""""" 139By default the CMake_ project will generate build files for building the 140static library. To build the shared version use:: 141 142 ... 143 cmake -DJANSSON_BUILD_SHARED_LIBS=1 .. 144 145Changing install directory (same as autoconf --prefix) 146"""""""""""""""""""""""""""""""""""""""""""""""""""""" 147Just as with the autoconf_ project you can change the destination directory 148for ``make install``. The equivalent for autoconfs ``./configure --prefix`` 149in CMake_ is:: 150 151 ... 152 cmake -DCMAKE_INSTALL_PREFIX:PATH=/some/other/path .. 153 make install 154 155.. _CMake: http://www.cmake.org 156 157 158Android 159------- 160 161Jansson can be built for Android platforms. Android.mk is in the 162source root directory. The configuration header file is located in the 163``android`` directory in the source distribution. 164 165 166Other Systems 167------------- 168 169On non Unix-like systems, you may be unable to run the ``./configure`` 170script. In this case, follow these steps. All the files mentioned can 171be found in the ``src/`` directory. 172 1731. Create ``jansson_config.h`` (which has some platform-specific 174 parameters that are normally filled in by the ``./configure`` 175 script). Edit ``jansson_config.h.in``, replacing all ``@variable@`` 176 placeholders, and rename the file to ``jansson_config.h``. 177 1782. Make ``jansson.h`` and ``jansson_config.h`` available to the 179 compiler, so that they can be found when compiling programs that 180 use Jansson. 181 1823. Compile all the ``.c`` files (in the ``src/`` directory) into a 183 library file. Make the library available to the compiler, as in 184 step 2. 185 186 187Building the Documentation 188-------------------------- 189 190(This subsection describes how to build the HTML documentation you are 191currently reading, so it can be safely skipped.) 192 193Documentation is in the ``doc/`` subdirectory. It's written in 194reStructuredText_ with Sphinx_ annotations. To generate the HTML 195documentation, invoke:: 196 197 make html 198 199and point your browser to ``doc/_build/html/index.html``. Sphinx_ 1.0 200or newer is required to generate the documentation. 201 202.. _reStructuredText: http://docutils.sourceforge.net/rst.html 203.. _Sphinx: http://sphinx.pocoo.org/ 204 205 206Compiling Programs that Use Jansson 207=================================== 208 209Jansson involves one C header file, :file:`jansson.h`, so it's enough 210to put the line 211 212:: 213 214 #include <jansson.h> 215 216in the beginning of every source file that uses Jansson. 217 218There's also just one library to link with, ``libjansson``. Compile and 219link the program as follows:: 220 221 cc -o prog prog.c -ljansson 222 223Starting from version 1.2, there's also support for pkg-config_:: 224 225 cc -o prog prog.c `pkg-config --cflags --libs jansson` 226 227.. _pkg-config: http://pkg-config.freedesktop.org/ 228