Compiling and Installing Jansson
================================
-This chapter explains how to compile and install the library itself.
-
-
-Compiling and Installing from a Source Tarball
-----------------------------------------------
+The Jansson source is available at
+http://www.digip.org/jansson/releases/.
Unpack the source tarball and change to the source directory:
no options to customize the resulting Jansson binary.)
The command ``make check`` runs the test suite distributed with
-Jansson. This step is not strictly necessary, but it may find possible
-problems that Jansson has on your platform. If any problems are found,
-please report them.
-
-.. _autoconf: http://www.gnu.org/software/autoconf/
-.. _automake: http://www.gnu.org/software/automake/
-.. _libtool: http://www.gnu.org/software/libtool/
-
-
-Compiling and Installing from Git
----------------------------------
+Jansson. Python_ is required to run the tests. This step is not
+strictly necessary, but it may find possible problems that Jansson has
+on your platform. If any problems are found, please report them.
If you obtained the source from a Git repository (or any other source
control system), there's no ``./configure`` script as it's not kept in
This command creates the ``./configure`` script, which can then be
used as described in the previous section.
+.. _autoconf: http://www.gnu.org/software/autoconf/
+.. _automake: http://www.gnu.org/software/automake/
+.. _libtool: http://www.gnu.org/software/libtool/
+.. _Python: http://www.python.org/
+
Installing Prebuilt Binary Packages
-----------------------------------
-Binary ``.deb`` packages for Ubuntu are available in the `Jansson
-PPA`_ at Launchpad_. Follow the instructions in the PPA ("Read about
-installing" link) to take the PPA into use. Then install the -dev
+Binary ``.deb`` packages for Ubuntu are available in `this PPA`_ at
+Launchpad_. Follow the instructions in the PPA ("Technical details
+about this PPA" link) to take the PPA into use. Then install the -dev
package::
- apt-get install libjansson-dev
+ sudo apt-get install libjansson-dev
-.. _Jansson PPA: http://launchpad.net/~petri/+archive/ppa
+.. _this PPA: http://launchpad.net/~petri/+archive/ppa
.. _Launchpad: http://launchpad.net/
+Building the Documentation
+--------------------------
+
+(This subsection describes how to build the HTML documentation you are
+currently reading, so it can be safely skipped.)
+
+Documentation is in the ``doc/`` subdirectory. It's written in
+reStructuredText_ with Sphinx_ annotations. To generate the HTML
+documentation, invoke::
+
+ cd doc/
+ sphinx-build . .build/html
+
+... and point your browser to ``.build/html/index.html``. Sphinx_ is
+required to generate the documentation.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Sphinx: http://sphinx.pocoo.org/
+
Compiling Programs Using Jansson
================================
The GitHub Commits API
======================
-The GitHub commits API is used by sending HTTP requests to URLs
+The `GitHub commits API`_ is used by sending HTTP requests to URLs
starting with ``http://github.com/api/v2/json/commits/``. Our program
only lists the latest commits, so the rest of the URL is
``list/USER/REPOSITORY/BRANCH``, where ``USER``, ``REPOSITORY`` and
``BRANCH`` are the GitHub user ID, the name of the repository, and the
-name of the branch whose commits are to be listed, respectively. The
-following definitions are used to build the request URL::
-
- #define URL_FORMAT "http://github.com/api/v2/json/commits/list/%s/%s/master"
- #define URL_SIZE 256
+name of the branch whose commits are to be listed, respectively.
GitHub responds with a JSON object of the following form:
static char *request(const char *url);
It takes the URL as a parameter, preforms a HTTP GET request, and
-returns a newly allocated string that contains the response body. For
-full details, refer to :download:`the code <github_commits.c>`, as the
-actual implementation is not important here.
+returns a newly allocated string that contains the response body. If
+the request fails, an error message is printed to stderr and the
+return value is *NULL*. For full details, refer to :download:`the code
+<github_commits.c>`, as the actual implementation is not important
+here.
+.. _GitHub commits API: http://develop.github.com/p/commits.html
.. _tutorial-the-program:
Like all the programs using Jansson, we need to include
:file:`jansson.h`.
+The following definitions are used to build the GitHub commits API
+request URL::
+
+ #define URL_FORMAT "http://github.com/api/v2/json/commits/list/%s/%s/master"
+ #define URL_SIZE 256
+
The following function is used when formatting the result to find the
first newline in the commit message::
returns *NULL* and sets error information to the :ctype:`json_error_t`
structure given as the second parameter. In this case, our program
prints the error information out and returns 1 from the main function.
-This check is really only to be sure, because we can assume that the
-GitHub API returns correct JSON to us.
-Next, we'll extract the ``commits`` array from the JSON response::
+Now we're ready to extract the data out of the decoded JSON response.
+The structure of the response JSON was explained in section
+:ref:`tutorial-github-commits-api`.
+
+First, we'll extract the ``commits`` array from the JSON response::
commits = json_object_get(root, "commits");
- if(!commits || !json_is_array(commits))
+ if(!json_is_array(commits))
{
fprintf(stderr, "error: commits is not an array\n");
return 1;
}
This is the array that contains objects describing latest commits in
-the repository. If the key ``commits`` doesn't exist,
-:cfunc:`json_object_get()` returns *NULL*. We also check that the
-returned value really is an array.
+the repository. We check that the returned value really is an array.
+If the key ``commits`` doesn't exist, :cfunc:`json_object_get()`
+returns *NULL*, but :cfunc:`json_is_array()` handles this case, too.
Then we proceed to loop over all the commits in the array::
The function :cfunc:`json_array_size()` returns the size of a JSON
array. First, we again declare some variables and then extract the
i'th element of the ``commits`` array using :cfunc:`json_array_get()`.
-We also check that the resulting value is a JSON object. (The
-structure of the response JSON was explained in
-:ref:`tutorial-github-commits-api`).
+We also check that the resulting value is a JSON object.
Next we'll extract the commit ID and commit message, and check that
they both are JSON strings::
id = json_object_get(commit, "id");
- if(!id || !json_is_string(id))
+ if(!json_is_string(id))
{
fprintf(stderr, "error: commit %d: id is not a string\n", i + 1);
return 1;
}
message = json_object_get(commit, "message");
- if(!message || !json_is_string(message))
+ if(!json_is_string(message))
{
fprintf(stderr, "error: commit %d: message is not a string\n", i + 1);
return 1;
}
After sending the HTTP request, we decoded the JSON text using
-:cfunc:`json_loads()`, remember? It returns a *new reference* to a
+:cfunc:`json_loads()`, remember? It returns a *new reference* to the
JSON value it decodes. When we're finished with the value, we'll need
to decrease the reference count using :cfunc:`json_decref()`. This way
Jansson can release the resources::
projects / jansson.git / commitdiff