|
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 .. _build-cmake: |
|
58 |
|
59 CMake (various platforms, including Windows) |
|
60 -------------------------------------------- |
|
61 |
|
62 Jansson can be built using CMake_. Create a build directory for an |
|
63 out-of-tree build, change to that directory, and run ``cmake`` (or ``ccmake``, |
|
64 ``cmake-gui``, or similar) to configure the project. |
|
65 |
|
66 See 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 |
|
75 Unix (Make files) |
|
76 ^^^^^^^^^^^^^^^^^ |
|
77 Generating 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 |
|
88 Then to build:: |
|
89 |
|
90 make |
|
91 make check |
|
92 make install |
|
93 |
|
94 Windows (Visual Studio) |
|
95 ^^^^^^^^^^^^^^^^^^^^^^^ |
|
96 Creating 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 |
|
107 You will now have a *Visual Studio Solution* in your build directory. |
|
108 To run the unit tests build the ``RUN_TESTS`` project. |
|
109 |
|
110 If you prefer a GUI the ``cmake`` line in the above example can |
|
111 be replaced with:: |
|
112 |
|
113 cmake-gui .. |
|
114 |
|
115 For command line help (including a list of available generators) |
|
116 for CMake_ simply run:: |
|
117 |
|
118 cmake |
|
119 |
|
120 To list available CMake_ settings (and what they are currently set to) |
|
121 for the project, run:: |
|
122 |
|
123 cmake -LH .. |
|
124 |
|
125 Mac OSX (Xcode) |
|
126 ^^^^^^^^^^^^^^^ |
|
127 If you prefer using Xcode instead of make files on OSX, |
|
128 do the following. (Use the same steps as |
|
129 for :ref:`Unix <build-cmake-unix>`):: |
|
130 |
|
131 ... |
|
132 cmake -G "Xcode" .. |
|
133 |
|
134 Additional CMake settings |
|
135 ^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
136 |
|
137 Shared library |
|
138 """""""""""""" |
|
139 By default the CMake_ project will generate build files for building the |
|
140 static library. To build the shared version use:: |
|
141 |
|
142 ... |
|
143 cmake -DJANSSON_BUILD_SHARED_LIBS=1 .. |
|
144 |
|
145 Changing install directory (same as autoconf --prefix) |
|
146 """""""""""""""""""""""""""""""""""""""""""""""""""""" |
|
147 Just as with the autoconf_ project you can change the destination directory |
|
148 for ``make install``. The equivalent for autoconfs ``./configure --prefix`` |
|
149 in 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 |
|
158 Android |
|
159 ------- |
|
160 |
|
161 Jansson can be built for Android platforms. Android.mk is in the |
|
162 source root directory. The configuration header file is located in the |
|
163 ``android`` directory in the source distribution. |
|
164 |
|
165 |
|
166 Other Systems |
|
167 ------------- |
|
168 |
|
169 On non Unix-like systems, you may be unable to run the ``./configure`` |
|
170 script. In this case, follow these steps. All the files mentioned can |
|
171 be found in the ``src/`` directory. |
|
172 |
|
173 1. 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 |
|
178 2. 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 |
|
182 3. 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 |
|
187 Building the Documentation |
|
188 -------------------------- |
|
189 |
|
190 (This subsection describes how to build the HTML documentation you are |
|
191 currently reading, so it can be safely skipped.) |
|
192 |
|
193 Documentation is in the ``doc/`` subdirectory. It's written in |
|
194 reStructuredText_ with Sphinx_ annotations. To generate the HTML |
|
195 documentation, invoke:: |
|
196 |
|
197 make html |
|
198 |
|
199 and point your browser to ``doc/_build/html/index.html``. Sphinx_ 1.0 |
|
200 or newer is required to generate the documentation. |
|
201 |
|
202 .. _reStructuredText: http://docutils.sourceforge.net/rst.html |
|
203 .. _Sphinx: http://sphinx.pocoo.org/ |
|
204 |
|
205 |
|
206 Compiling Programs that Use Jansson |
|
207 =================================== |
|
208 |
|
209 Jansson involves one C header file, :file:`jansson.h`, so it's enough |
|
210 to put the line |
|
211 |
|
212 :: |
|
213 |
|
214 #include <jansson.h> |
|
215 |
|
216 in the beginning of every source file that uses Jansson. |
|
217 |
|
218 There's also just one library to link with, ``libjansson``. Compile and |
|
219 link the program as follows:: |
|
220 |
|
221 cc -I /usr/include/jansson -o prog prog.c -ljansson |
|
222 |
|
223 Starting 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/ |