diff options
author | Eric Haszlakiewicz <erh+git@nimenees.com> | 2020-04-11 03:24:51 +0000 |
---|---|---|
committer | Eric Haszlakiewicz <erh+git@nimenees.com> | 2020-04-11 03:24:51 +0000 |
commit | 270dc2f999b0669a8836dbca1a0900f5efe09686 (patch) | |
tree | ef048e2407aea0c95b6d3b597ee62827e59d0e89 | |
parent | 0734c5303d25245ed172fc26ceef31f76417cbaa (diff) | |
download | json-c-270dc2f999b0669a8836dbca1a0900f5efe09686.tar.gz |
Update README.md to remove autoconf instructions in favor of cmake.
-rw-r--r-- | README.md | 196 |
1 files changed, 75 insertions, 121 deletions
@@ -3,9 +3,11 @@ 1. [Overview and Build Status](#overview) 2. [Building on Unix](#buildunix) -3. [Install Prerequisites](#installprereq) -4. [Building with partial threading support](#buildthreaded) -5. [Building with CMake](#CMake) + * [Prerequisites](#installprereq) + * [Build commands](#buildcmds) +3. [CMake options](#CMake) +4. [Testing](#testing) +5. [Building with `vcpkg`](#buildvcpkg) 6. [Linking to libjson-c](#linking) 7. [Using json-c](#using) @@ -24,116 +26,90 @@ construct JSON objects in C, output them as JSON formatted strings and parse JSON formatted strings back into the C representation of JSON objects. It aims to conform to [RFC 7159](https://tools.ietf.org/html/rfc7159). -Building on Unix and Windows with `vcpkg`, `gcc`/`g++`, `curl`, `unzip`, and `tar` --------------------------------------------------- - -You can download and install JSON-C using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager: - - git clone https://github.com/Microsoft/vcpkg.git - cd vcpkg - ./bootstrap-vcpkg.sh - ./vcpkg integrate install - vcpkg install json-c - -The JSON-C port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. - -Building on Unix with `git`, `gcc` and `autotools` <a name="buildunix"></a> +Building on Unix with `git`, `gcc` and `cmake` <a name="buildunix"></a> -------------------------------------------------- Home page for json-c: https://github.com/json-c/json-c/wiki -### Prerequisites: - -See also the "Installing prerequisites" section below. +### Prerequisites: <a name="installprereq"></a> - `gcc`, `clang`, or another C compiler - - `libtool>=2.2.6b` -If you're not using a release tarball, you'll also need: + - cmake>=2.8, >=3.16 recommended - - `autoconf>=2.64` (`autoreconf`) - - `automake>=1.13` +To generate docs you'll also need: + - `doxygen>=1.8.13` -Make sure you have a complete `libtool` install, including `libtoolize`. +If you are on a relatively modern system, you'll likely be able to install +the prerequisites using your OS's packaging system. -To generate docs (e.g. as part of make distcheck) you'll also need: - - `doxygen>=1.8.13` +### Install using apt (e.g. Ubuntu 16.04.2 LTS) +```sh +sudo apt install git +sudo apt install cmake +sudo apt install doxygen # optional +sudo apt install valgrind # optional +``` -### Build instructions: +### Build instructions: <a name="buildcmds"></a> `json-c` GitHub repo: https://github.com/json-c/json-c ```sh $ git clone https://github.com/json-c/json-c.git -$ cd json-c -$ sh autogen.sh +$ mkdir json-c-build +$ cd json-c-build +$ cmake ../json-c # See CMake section below for custom arguments ``` -followed by +Note: it's also possible to put your build directory inside the json-c +source directory, or even not use a separate build directory at all, but +certain things might not work quite right (notably, `make distcheck`) + +Then: ```sh -$ ./configure # --enable-threading $ make +$ make test +$ make USE_VALGRIND=0 test # optionally skip using valgrind $ make install ``` -To build and run the test programs: - -```sh -$ make check -$ make USE_VALGRIND=0 check # optionally skip using valgrind -``` -Install prerequisites <a name="installprereq"></a> ------------------------ +### Generating documentation with Doxygen: -If you are on a relatively modern system, you'll likely be able to install -the prerequisites using your OS's packaging system. +The libray documentation can be generated directly from the source codes using Doxygen tool: -### Install using apt (e.g. Ubuntu 16.04.2 LTS) ```sh -sudo apt install git -sudo apt install autoconf automake libtool -sudo apt install valgrind # optional +# in build directory +make doc +google-chrome doc/html/index.html ``` -Then start from the "git clone" command, above. -### Manually install and build autoconf, automake and libtool +CMake Options <a name="CMake"></a> +-------------------- + +The json-c library is built with [CMake](https://cmake.org/cmake-tutorial/), +which can take a few options. -For older OS's that don't have up-to-date versions of the packages will -require a bit more work. For example, CentOS release 5.11, etc... +Variable | Type | Description +---------------------|--------|-------------- +CMAKE_INSTALL_PREFIX | String | The install location. +CMAKE_BUILD_TYPE | String | Defaults to "debug" +BUILD_SHARED_LIBS | Bool | The default build generates a dynamic (dll/so) library. Set this to OFF to create a static library instead. +ENABLE_RDRAND | Bool | Enable RDRAND Hardware RNG Hash Seed +ENABLE_THREADING | Bool | Enable partial threading support +DISABLE_WERROR | Bool | Disable use of -Werror +DISABLE_BSYMBOLIC | Bool | Disable use of -Bsymbolic-functions + +Pass these options as `-D` on CMake's command-line. ```sh -curl -O http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -curl -O http://ftp.gnu.org/gnu/automake/automake-1.15.tar.gz -curl -O http://ftp.gnu.org/gnu/libtool/libtool-2.2.6b.tar.gz - -tar xzf autoconf-2.69.tar.gz -tar xzf automake-1.15.tar.gz -tar xzf libtool-2.2.6b.tar.gz - -export PATH=${HOME}/ac_install/bin:$PATH - -(cd autoconf-2.69 && \ - ./configure --prefix ${HOME}/ac_install && \ - make && \ - make install) - -(cd automake-1.15 && \ - ./configure --prefix ${HOME}/ac_install && \ - make && \ - make install) - -(cd libtool-2.2.6b && \ - ./configure --prefix ${HOME}/ac_install && \ - make && \ - make install) +cmake -DBUILD_SHARED_LIBS=OFF ... ``` - -Building with partial threading support <a name="buildthreaded"></a> ----------------------------------------- +### Building with partial threading support Although json-c does not support fully multi-threaded access to object trees, it has some code to help make its use in threaded programs @@ -142,49 +118,24 @@ json_object_get() and json_object_put(). Since this may have a performance impact, of at least 3x slower according to https://stackoverflow.com/a/11609063, it is disabled by -default. You may turn it on by adjusting your configure command with: - --enable-threading +default. You may turn it on by adjusting your cmake command with: + -DENABLE_THREADING=ON Separately, the default hash function used for object field keys, lh_char_hash, uses a compare-and-swap operation to ensure the random seed is only generated once. Because this is a one-time operation, it is always compiled in when the compare-and-swap operation is available. -Building with CMake <a name="CMake"></a> --------------------- -To use [CMake](https://cmake.org/cmake-tutorial/), build it like: +### cmake-configure wrapper script -```sh -mkdir build -cd build -cmake ../ -make -``` - -CMake can take a few options. - -Variable | Type | Description ----------------------|--------|-------------- -CMAKE_INSTALL_PREFIX | String | The install location. -BUILD_SHARED_LIBS | Bool | The default build generates a dynamic (dll/so) library. Set this to OFF to create a static library instead. -ENABLE_RDRAND | Bool | Enable RDRAND Hardware RNG Hash Seed -ENABLE_THREADING | Bool | Enable partial threading support - -Pass these options as `-D` on CMake's command-line. - -```sh -cmake -DBUILD_SHARED_LIBS=OFF ... -``` - -**In addition, you can also use cmake-configure: Wrapper around cmake to emulate useful options.** - -To use cmake-configure, build it like: +For those familiar with the old autoconf/autogen.sh/configure method, +there is a `cmake-configure` wrapper script to ease the transition to cmake. ```sh mkdir build cd build -../cmake-configure --disable-werror +../cmake-configure --prefix=/some/install/path make ``` @@ -200,7 +151,9 @@ cmake-configure can take a few options. | disable-Bsymbolic | Avoid linking with -Bsymbolic-function | | disable-werror | Avoid treating compiler warnings as fatal errors | -Testing with cmake: + +Testing: <a name="testing"></a> +---------- By default, if valgrind is available running tests uses it. That can slow the tests down considerably, so to disable it use: @@ -208,11 +161,12 @@ That can slow the tests down considerably, so to disable it use: export USE_VALGRIND=0 ``` -To run tests: +To run tests a separate build directory is recommended: ```sh mkdir build-test cd build-test -# VALGRIND=1 causes -DVALGRIND=1 to be included when building +# VALGRIND=1 causes -DVALGRIND=1 to be passed when compiling code +# which uses slightly slower, but valgrind-safe code. VALGRIND=1 cmake .. make @@ -233,20 +187,20 @@ JSONC_TEST_TRACE=1 make test ``` and check the log files again. -To get doxygen documentation: -The libray documentation can be generated directly from the source codes using Doxygen tool: +Building on Unix and Windows with `vcpkg` <a name="buildvcpkg"></a> +-------------------------------------------------- -```sh -make doc -google-chrome ../doc/html/index.html -``` +You can download and install JSON-C using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager: + + git clone https://github.com/Microsoft/vcpkg.git + cd vcpkg + ./bootstrap-vcpkg.sh + ./vcpkg integrate install + vcpkg install json-c -To uninstall: +The JSON-C port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository. -```sh -make uninstall -``` Linking to `libjson-c` <a name="linking"> ---------------------- |